# Authentication overview

> The ways to authenticate with Kustomer (API keys, OAuth 2.0 and chat keys) and how to choose between them.

Source: https://developer.kustomer.com/docs/get-started/authentication

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

```http
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

| Method                                                                        | Acts as                                  | Best for                                                                                | Lifetime                                                  |
| ----------------------------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [API key](https://developer.kustomer.com/docs/get-started/api-keys-and-roles) | A machine user with fixed roles          | Server-to-server integrations, scheduled syncs, internal tools                          | Until it expires or is deleted                            |
| [OAuth 2.0](https://developer.kustomer.com/docs/get-started/oauth)            | The signed-in Kustomer user              | Tools that act on behalf of individual agents or admins, such as CLIs and AI assistants | Access token about 24 hours, renewed with a refresh token |
| [Chat key](https://developer.kustomer.com/docs/chat/web)                      | An anonymous or identified chat customer | Kustomer Chat in your website or mobile app                                             | Until it expires or is deleted                            |

```mermaid
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"]
```

> **Never ship an API key to a browser or mobile app:** API keys can read and write your org's data. Code on customer devices should only ever hold a chat key, which has the single `org.tracking` role and is designed to be public.

## 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](https://developer.kustomer.com/docs/get-started/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.

_Step-by-step sequence of the OAuth 2.0 authorization code flow with PKCE between your app, the browser, the Kustomer web host and the Kustomer API host: generate a verifier, redirect to /oauth/authorize, user approves, redirect back with a code, POST /oauth/token, receive access and refresh tokens, call the API, refresh before expiry._

The [OAuth 2.0](https://developer.kustomer.com/docs/get-started/oauth) 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:

`GET /v1/auth/tokens/current` ([reference](https://developer.kustomer.com/api/access-management/get-current-auth-token))

`GET /v1/users/current` ([reference](https://developer.kustomer.com/api/access-management/get-current-user))

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

| Status | Code           | Meaning                                                                                          | Fix                                                                                                                    |
| ------ | -------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `401`  | `unauthorized` | Missing, malformed, expired or deleted token, or a request from outside the key's IP restriction | Check the `Bearer ` prefix, the key's status and its CIDR range                                                        |
| `403`  | `forbidden`    | The token is valid but lacks a role the operation requires                                       | Create a key with the needed role. Each reference page lists the accepted roles.                                       |
| `4xx`  | none           | `Auth token associated with pod prod2 but request is being handled by prod1`                     | Use your org host. See [Regions and base URLs](https://developer.kustomer.com/docs/get-started/regions-and-base-urls). |