> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alumio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request authentication

> Authenticate by a header value retrieved through a different requests.

export const FormField = ({property, label, required = false, diType, uiPatterns, children}) => {
  const patterns = Array.isArray(uiPatterns) ? uiPatterns : uiPatterns ? [uiPatterns] : [];
  return <div style={{
    margin: '1.5rem 0'
  }}>
      <div style={{
    display: 'flex',
    alignItems: 'baseline',
    flexWrap: 'wrap',
    gap: '0.5rem',
    marginBottom: '0.25rem'
  }}>
        <strong>{label}</strong>
        <span style={{
    fontSize: '0.7rem',
    fontWeight: 600,
    textTransform: 'uppercase',
    letterSpacing: '0.04em',
    color: required ? '#6241f5' : '#6b7280'
  }}>
          {required ? 'Required' : 'Optional'}
        </span>
      </div>

      <div>{children}</div>

      {diType || patterns.length > 0 ? <p style={{
    fontSize: '0.85rem',
    color: '#6b7280',
    marginBottom: 0
  }}>
          {diType ? <>
              See the <a href={`/references/${diType}`}>{diType}</a> reference.{' '}
            </> : null}
          {patterns.length > 0 ? <>
              Accepts a <a href={`/documentation/placeholders-and-patterns/patterns#${patterns[0]}`}>pattern</a>.
            </> : null}
        </p> : null}
    </div>;
};

Authenticates requests with a value that is first fetched by calling another endpoint. Use this when an API hands you a session token, ticket, or cookie from a login or token call, and you then have to send that value on every following request. Alumio makes the lookup call for you, reads the value out of the response (from a header, a cookie, or the body), and adds it as a header on the requests of the connection. It can also cache the value so the lookup is not repeated on every single request.

This documentation describes: [Schema](/schemas/http-authentication-configurator/request)

## Fields

<FormField property="headerName" label="Header name" required>
  The name of the header that the fetched value is placed in on your outgoing requests. This is the header the target API expects to receive for authentication, for example `Authorization` or `X-Auth-Token`.
</FormField>

<FormField property="request.uri" label="Request URI" required>
  The address of the endpoint that returns the authentication value, such as a login or token endpoint. If the selected HTTP API connection already has a base URI set, start this with a slash to append to it.
</FormField>

<FormField property="request.method" label="Request Method" required>
  The HTTP method used for the lookup call, for example `get` or `post`. Defaults to `get`.
</FormField>

<FormField property="request.payload" label="Request Parameters">
  The data sent with the lookup call, such as the username and password a login endpoint expects. Defaults to `&{@}`, which passes through the current data. See [Placeholders](/references/placeholders) for how to insert values.
</FormField>

<FormField property="request.serializer" label="Request formatter" diType="serializer">
  The format the lookup call's body is sent in, for example JSON. Choose the format the endpoint expects.
</FormField>

<FormField property="request.inputTransformer" label="Request input transformer" diType="transformer">
  An optional step that prepares the data before it is used in the lookup call, for example to assemble the login parameters.
</FormField>

<FormField property="client" label="HTTP API connection" diType="http-client">
  The connection used to make the lookup call. Leave it on the default connection unless the lookup endpoint needs different connection settings.
</FormField>

<FormField property="deserializer" label="Response parser" diType="stream-deserializer">
  The format of the lookup call's response body, for example JSON. This lets Alumio read values out of the response when you take the value from the response body.
</FormField>

<FormField property="source.sourceType" label="Source" required>
  Where in the lookup response the authentication value is found. Choose Headers to read it from a response header, Cookies to read it from a cookie, or Response body to read it from the body. Your choice decides which of the next fields appears.
</FormField>

<FormField property="source.headerName" label="Header name (source)">
  Shown when Source is Headers. The name of the response header whose value is used. That value is then placed in the header you set above.
</FormField>

<FormField property="source.cookieName" label="Cookie name">
  Shown when Source is Cookies. The name of the cookie whose value is used.
</FormField>

<FormField property="source.responseBodyTemplate" label="Template">
  Shown when Source is Response body. A template that pulls the value out of the parsed response body. Defaults to `&{@}`, the whole response. See [Placeholders](/references/placeholders) for the syntax.
</FormField>

<FormField property="enableCache" label="Enable caching of the authentication header">
  Turn this on to remember the fetched value and reuse it, instead of making the lookup call before every request. When on, you also choose where it is stored.
</FormField>

<FormField property="cacheStorage" label="Storage" diType="storage">
  Shown when caching is on. The storage used to hold the cached authentication value.
</FormField>

## Sample data

This feature adds authentication to a live HTTP connection rather than transforming data, so there is no before/after to show. A typical configuration that logs in at `/auth/login`, reads a token from the response body, and sends it back as an `Authorization` header looks like this:

| Field          | Value             |
| -------------- | ----------------- |
| Header name    | `Authorization`   |
| Request URI    | `/auth/login`     |
| Request Method | `post`            |
| Source         | Response body     |
| Template       | `Bearer &{token}` |

With these settings, Alumio calls `/auth/login`, reads the `token` field from the response, and adds `Authorization: Bearer <token>` to each request the connection sends.

```json Configuration theme={null}
{
  "prototype": "request",
  "parameters": {
    "headerName": "Authorization",
    "request": {
      "uri": "/auth/login",
      "method": "post",
      "payload": { "username": "your-username", "password": "your-password" }
    },
    "source": {
      "sourceType": "response-body",
      "responseBodyTemplate": "Bearer &{token}"
    }
  }
}
```