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. Only credentials with a token_type of text can be created here — the credential value is sent as a request header. 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_valuestringrequired

The credential value. Stored encrypted and never returned by any endpoint.

Example:"sk_live_9f3c2a7b41e8"
request_header_keystringrequired

The request header the credential is sent in.

Example:"Authorization"
token_prefixstring

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

Example:"Bearer"
descriptionstring

An optional description of what the credential is used for.

Example:"Used by the order status connector"
domainstring

An optional domain to scope the credential to.

Example:"api.fulfilment.example.com"
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",
    "domain": "api.fulfilment.example.com"
  }'

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": "api.fulfilment.example.com",
  "created_at": "2025-11-15T09:30:00Z",
  "updated_at": "2025-11-15T09:30:00Z"
}