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

# Handle cookie-based tokens

> Configure adapters when the system returns authentication tokens in cookies.

This system uses two-step authentication, but instead of returning the token in the response body it returns it in a cookie — the same way a browser session would work. Subsequent requests must also send the token as a cookie. Additionally, the token request requires an `Accept: */*` header, and the response is not JSON.

## Configuration

This scenario requires changes to the service instance configuration, `action.json`, and the response schema.

### Service instance configuration

Update `auth_field` and `auth_field_format` in the `authentication` section so the token is placed in the `Cookie` header on 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.Cookie",
  "auth_field_format": "gmsSessionID={token}"
}
```

### action.json

Set `responseDatatype` to `PLAIN` since the token response is not JSON. Add an `Accept: */*` header to override the adapter library's default `Accept` header.

```json
{
  "name": "getToken",
  "protocol": "REST",
  "method": "POST",
  "entitypath": "{base_path}/{version}/authentication/login",
  "requestSchema": "tokenReqSchema.json",
  "responseSchema": "tokenRespSchema.json",
  "timeout": 0,
  "sendEmpty": false,
  "requestDatatype": "JSON",
  "responseDatatype": "PLAIN",
  "headers": {
    "Accept": "*/*"
  },
  "responseObjects": [
    {
      "type": "default",
      "key": "",
      "mockFile": "mockdatafiles/getToken-default.json"
    }
  ]
}
```

### Response schema

Add a `placement` field set to `"header"` on the `token` property to tell the adapter library to look for the token in the response headers rather than the body. Set `external_name` to the specific header field that contains the cookie value.

```json
{
  "$id": "respTokenSchema.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",
      "placement": "header",
      "external_name": "set-cookie.gmsSessionID"
    }
  },
  "definitions": {}
}
```

> Configure adapters when the system returns authentication tokens in cookies.