Create Token
/v1/auth/tokensCallable without an API key.
Logs in to an organization with domain, email, and password.
NOTE
Machine tokens can be created within the settings section by an administrator for API, tracking, and hook access
API keys and auth tokens
An auth token is the bearer credential sent with every API request. API keys are long-lived tokens that belong to a machine user with a fixed set of roles; session tokens are created when a person signs in. These endpoints list, inspect and revoke tokens.
Every request to the Kustomer API carries a token in Authorization: Bearer <token>, and each token belongs to a user. API keys are created by admins in Settings › Security › API Keys. Each one is backed by its own machine user, has roles that are chosen when it's created and can't be edited, and can have an expiry and an IP range restriction. Session tokens are created when a person signs in to Kustomer and act with that person's roles. A token works until it expires or is deleted.
POST /v1/auth/tokens is the sign-in call behind the second kind: it takes an org domain with an email and password (or a Google or SAML sign-in token) and returns a session token for that person. It does not create API keys. Integrations should use an API key or OAuth rather than storing someone's password.
What a token record shows
| Field | Meaning |
|---|---|
name |
The token's name; for an API key, the name it was given in Settings |
roles |
What the token is allowed to do |
lastTokenChars |
The last characters of the token, to tell keys apart |
lastAccessedAt |
When it was last used |
ipAddress, userAgent |
The IP address and client recorded with the token |
user |
The user the token acts as, in relationships |
The full token value is only returned when the token is created. After that, nothing in the API returns it again, so store a new API key in your secrets manager immediately.
Whose tokens you can see
GET /v1/auth/tokens needs a security admin role and by default returns the current user's tokens. Pass userType (user, machine, limited or app) to list tokens for that kind of user; userType=machine lists your org's API keys. filter matches the start of the token name. Any token can read or delete itself through /v1/auth/tokens/current, and the /{id} endpoints also work on your own tokens; acting on someone else's needs org.admin.security or org.permission.security.
Which endpoint to use
| To | Call |
|---|---|
| Check which user and roles the token you're using has | GET /v1/auth/tokens/current |
| Revoke the token you're using, such as on sign-out | DELETE /v1/auth/tokens/current |
| List tokens, such as every API key in the org | GET /v1/auth/tokens |
| Read or revoke a specific token | GET or DELETE /v1/auth/tokens/{id} |
| Sign a person in with their credentials | POST /v1/auth/tokens |
Because a key's roles can't change, rotating a key means replacing it: create a new key with the same roles, deploy it, watch the old key's lastAccessedAt until it stops moving, then delete the old key. A deleted or expired token fails with 401. GET /v1/auth/tokens/current works with any valid token, which makes it a good health check. Token lists are paginated with page and pageSize (up to 500).
Request body
application/jsonResponses
Created