Authentication overview

Every API request carries a bearer token in the Authorization header:

GET /v1/users/current HTTP/1.1
Host: acme.api.kustomerapp.com
Authorization: Bearer eyJhbGciOi...

What changes is where the token comes from and whose identity it carries.

Choose a method

flowchart TD
  Q1{"Does the code run on a<br/>customer's device or browser?"} -- Yes --> CHAT["Chat key<br/>(role org.tracking only)"]
  Q1 -- No --> Q2{"Should actions be attributed<br/>to individual Kustomer users?"}
  Q2 -- Yes --> OAUTH["OAuth 2.0<br/>authorization code + PKCE"]
  Q2 -- No --> KEY["API key<br/>with least-privilege roles"]

API keys in brief

An admin creates keys in Settings › Security › API Keys. Each key:

• is backed by its own machine user, which appears as the author of anything the key creates;
• has a set of roles chosen at creation that can't be changed afterwards;
• can expire after a number of days, or never;
• can be limited to a CIDR IP range;
• is shown once, when it's created.

Read API keys and roles for the role naming scheme and least-privilege recipes.

OAuth in brief

Kustomer supports the OAuth 2.0 authorization code flow with PKCE. Users sign in at their org's web host (https://acme.kustomerapp.com/oauth/authorize), and your app exchanges the code at the API host (https://acme.api.kustomerapp.com/oauth/token). The OAuth client is a private app installed in the org, with redirectUris in its app definition.

The OAuth 2.0 page has the full parameter reference and a working example.

Checking a token

Two endpoints work with any valid token and are handy for health checks:

The first describes the token (name, roles, last access). The second returns the user it acts as: the machine user for API keys, or the signed-in person for OAuth.

Authentication errors