> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/adapters/authentication/methods/multi-step/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Multi-step authentication

> How to configure multi-step authentication (MSA) in an adapter, including step definitions, schema files, and token caching.

Multi-step authentication (MSA) is a verification process that requires two or more sequential steps before the adapter obtains the token needed for subsequent requests. Each step can pass data from its response into the next step's request.

## Configure MSA

MSA is configured entirely in the `authentication` section of theItential Platform service instance configuration for the adapter, accessible throughItential Platform Admin Essentials. For a full description of all authentication properties, see [Service instance configuration](/adapters/configure/service-instance-configuration/properties/overview).

Set `auth_method` to `"multi_step_authentication"`.

Each step in the authentication sequence is defined as an entry in the `multiStepAuthCalls` array. Every step can have corresponding schema files in `/entities/.system`:

* Request schema: `schemaTokenReq_MFA_Step_[number]`
* Response schema: `schemaTokenResp_MFA_Step_[number]`

After all steps complete, `auth_field` and `auth_field_format` define where and how the final token is placed in subsequent requests.

### Step fields

| Field                    | Description                                                                                                                                                                                                                                        |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                   | A unique name for the step. Other steps reference this step's response values using this name.                                                                                                                                                     |
| `requestFields`          | The fields to include in this step's request. Field names prefixed with `header.` are sent as HTTP headers (for example, `header.jx-session` sends the value as the `jx-session` request header). All other fields are placed in the request body. |
| `responseFields`         | The fields from this step's response that are exposed for use by subsequent steps. The value of each field must match the `external_name` set in the corresponding `schemaTokenResp_MFA_Step_[number]` file.                                       |
| `successfulResponseCode` | The expected HTTP response code for this step. Intermediate steps may return codes outside the standard success range (200–299, 300–308). Set the expected code here so the adapter does not treat it as an error.                                 |

## Configure token caching

Use the following properties to control how the final token is cached:

| Field           | Description                                                                                                                                                                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `token_cache`   | Storage location for the token. Supported values: `local` (in-memory) or `redis`.                                                                                                                                                                                                                                        |
| `token_timeout` | How long the token is valid, in milliseconds. When set to a value greater than zero, the token is refreshed each time the timeout elapses. **Must be greater than one minute (60000 ms).** When set to `0`, caching is based on the expiry date returned in the `expires` attribute of the final step's response schema. |

## Example

This example shows a two-step MSA flow. The first step (`getSession`) authenticates with credentials and receives a session token. The second step (`getToken`) uses that session token, along with a one-time password, to retrieve the final authorization token.

```json
"authentication": {
  "auth_method": "multi_step_authentication",
  "token_URI_path": "/v3/auth/tokens",
  "multiStepAuthCalls": [
    {
      "name": "getSession",
      "requestFields": {
        "username": "Alice",
        "password": "Alice-secret",
        "grant_type": "gt-1",
        "client_secret": "cs-1",
        "client_id": "cid-1"
      },
      "responseFields": {
        "session": "session"
      },
      "successfulResponseCode": 401
    },
    {
      "name": "getToken",
      "requestFields": {
        "header.jx-session": "{getSession.responseFields.session}",
        "timedOneTimePassword": "123456"
      },
      "responseFields": {
        "token": "token"
      },
      "successfulResponseCode": 201
    }
  ],
  "auth_field": "header.headers.xsx-authorization",
  "auth_field_format": "Bearer {token}",
  "token_cache": "local",
  "token_timeout": 120000,
  "invalid_token_error": 401,
  "auth_logging": true
}
```

> How to configure multi-step authentication (MSA) in an adapter, including step definitions, schema files, and token caching.