Skip to content
Home/
REST API Reference
/
/
Create an auth token

Create an auth token

Request

Stores a third-party credential in your workspace so a data connector can authenticate outbound requests with it. Set token_type to text (the default) to send the credential value as a request header yourself, or to oauth to have Intercom exchange OAuth client credentials for an access token and keep it refreshed. The value you supply is stored encrypted and is never returned by any endpoint, including this one.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version_preview)

Preview Intercom API version. Used for closed beta endpoints or other features under managed availability.

Default:"Preview"
Value:"Preview"
Example:Preview
Bodyapplication/jsonrequired
namestringrequired

A name for the credential, so a teammate can identify it later.

Example:"Fulfilment API key"
token_typestring

The type of credential to store. Defaults to text.

Enum:"text""oauth"
Example:"text"
token_valuestring

The credential value. Required when token_type is text. Must be omitted when token_type is oauth. Stored encrypted and never returned by any endpoint.

Example:"sk_live_9f3c2a7b41e8"
request_header_keystring

The request header the credential is sent in. Required when token_type is text. Must be omitted when token_type is oauth, where it is fixed to Authorization.

Example:"Authorization"
token_prefixstring

An optional prefix placed before the credential value in the header, for example Bearer. Must be omitted when token_type is oauth, where it is fixed to Bearer.

Example:"Bearer"
descriptionstring

An optional description of what the credential is used for.

Example:"Used by the order status connector"
oauth_configurationobject(OAuth Configuration)

The OAuth client-credentials configuration Intercom uses to obtain and refresh an access token. Required when token_type is oauth. Must be omitted when token_type is text.

curl -i -X POST \
  https://api.intercom.io/auth_tokens \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "name": "Fulfilment API key",
    "token_value": "sk_live_9f3c2a7b41e8",
    "request_header_key": "Authorization",
    "token_prefix": "Bearer",
    "description": "Used by the order status connector"
  }'

Responses

successful

Bodyapplication/json
typestring

The type of object - auth_token.

Value:"auth_token"
Example:"auth_token"
idstring

The unique identifier for the auth token.

Example:"12345"
namestring or null

The name given to the credential when it was created.

Example:"Fulfilment API key"
descriptionstring or null

An optional description of what the credential is used for.

Example:"Used by the order status connector"
token_typestring or null

How the credential is presented to the external API, for example as a header value or an HMAC signature.

Example:"text"
request_header_keystring or null

The request header the credential is sent in.

Example:"Authorization"
token_prefixstring or null

The prefix placed before the credential value in the header, for example Bearer.

Example:"Bearer"
domainstring or null

The domain the credential is scoped to, if one was set.

Example:"api.fulfilment.example.com"
created_atstring or null

The time the credential was created, as an ISO 8601 timestamp.

Example:"2025-11-15T09:30:00Z"
updated_atstring or null

The time the credential was last updated, as an ISO 8601 timestamp.

Example:"2026-01-20T14:22:15Z"
Response
{
  "type": "auth_token",
  "id": "12345",
  "name": "Fulfilment API key",
  "description": "Used by the order status connector",
  "token_type": "text",
  "request_header_key": "Authorization",
  "token_prefix": "Bearer",
  "domain": null,
  "created_at": "2025-11-15T09:30:00Z",
  "updated_at": "2025-11-15T09:30:00Z"
}