> 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/oauth/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# OAuth authentication

> How to configure OAuth client credentials authentication in an adapter, including service instance configuration and endpoint configuration changes.

OAuth authentication follows the two-step token pattern but has its own standards. This page covers the `client_credentials` grant type, a common OAuth flow used for system-to-system authentication.

In a typical OAuth `client_credentials` flow:

1. The adapter sends a `client_id`, `client_secret`, and `grant_type` in the initial token request. The request body is usually URL-encoded.
2. The external system returns a bearer token in the `access_token` field of the response.
3. Subsequent requests include this token, prefixed with `Bearer`, in the `Authorization` header.

## Configure the service instance configuration

Update the `authentication` section of theItential Platform service instance configuration for the adapter inItential Platform Admin Essentials with the following properties:

* Set `client_id` to the client ID provided by the external system.
* Set `client_secret` to the client secret provided by the external system.
* Set `grant_type` to `"client_credentials"`.
* Set `auth_field` to `"header.headers.Authorization"` — the location of the token on all subsequent requests.
* Set `auth_field_format` to `"Bearer {token}"` — the format of the token on all subsequent requests.

```json
"authentication": {
  "auth_method": "request_token",
  "username": "username",
  "password": "password",
  "token": "",
  "invalid_token_error": 401,
  "token_timeout": 180000,
  "token_cache": "local",
  "auth_field": "header.headers.Authorization",
  "auth_field_format": "Bearer {token}",
  "client_id": "client-id-you-get-for-system",
  "client_secret": "client-secret-you-get-for-system",
  "grant_type": "client_credentials"
}
```

## Configure the endpoint configuration

The endpoint configuration is located at `/adapter-home-dir/entities/.system`. If OAuth support has already been contributed back to the adapter repository, these changes may already be in place.

If you are using an open-source adapter and make OAuth changes, consider contributing them back to the adapter repository.

### action.json

The token request for OAuth uses `URLENCODE` as the `requestDatatype`. This causes the adapter library to URL-encode the request body before sending it, producing a payload like:

```
client_id=sdjdajdksj&client_secret=asdajdfklajd&grant_type=client_credentials
```

```json
{
  "name": "getToken",
  "protocol": "REST",
  "method": "POST",
  "entitypath": "/oauth_token.do",
  "requestSchema": "oAuthTokenRequest.json",
  "responseSchema": "oAuthTokenResponse.json",
  "timeout": 0,
  "sendEmpty": false,
  "requestDatatype": "URLENCODE",
  "responseDatatype": "JSON",
  "headers": {},
  "responseObjects": [
    {
      "type": "default",
      "key": "",
      "mockFile": "mockdatafiles/getToken-default.json"
    }
  ]
}
```

The request and response schemas can be named differently from the defaults, but the values in `action.json` must be relative paths to existing files in the endpoint configuration.

### Request schema

The request schema (`oAuthTokenRequest.json`) adds `grant_type`, `client_secret`, and `client_id` to the token request body. Although these values are defined in the service instance configuration, Adapter Builder does not add them to the schema automatically.

```json
{
  "$id": "oAuthTokenRequest.json",
  "type": "object",
  "schema": "http://json-schema.org/draft-07/schema#",
  "translate": true,
  "dynamicfields": true,
  "properties": {
    "ph_request_type": {
      "type": "string",
      "description": "type of request (internal to adapter)",
      "default": "getToken",
      "enum": ["getToken"],
      "external_name": "ph_request_type"
    },
    "grant_type": {
      "type": "string",
      "description": "type of auth",
      "external_name": "grant_type"
    },
    "client_secret": {
      "type": "string",
      "description": "secret used during login",
      "external_name": "client_secret"
    },
    "client_id": {
      "type": "string",
      "description": "client ID",
      "external_name": "client_id"
    },
    "username": {
      "type": "string",
      "description": "username to log in with",
      "external_name": "username"
    },
    "password": {
      "type": "string",
      "description": "password to log in with",
      "external_name": "password"
    }
  },
  "definitions": {}
}
```

### Response schema

The response schema (`oAuthTokenResponse.json`) maps the `access_token` field in the response to `token` for use by the adapter.

```json
{
  "$id": "oAuthTokenResponse.json",
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "translate": true,
  "properties": {
    "ph_request_type": {
      "type": "string",
      "description": "type of request (internal to adapter)",
      "default": "getToken",
      "enum": ["getToken"],
      "external_name": "ph_request_type"
    },
    "token": {
      "type": "string",
      "description": "the token returned from the system",
      "external_name": "access_token"
    }
  },
  "definitions": {}
}
```

> How to configure OAuth client credentials authentication in an adapter, including service instance configuration and endpoint configuration changes.