Skip to main content

Authentication

Every Developer API request is authenticated with a Chatley API key sent as a Bearer token. There are no unauthenticated endpoints.

Create an API key​

  1. In Chatley, open Integrations & API Keys → API Keys.
  2. Select Create API Key.
  3. Give the key a name and select POST as its key type.
  4. Copy the key and store it somewhere safe. Chatley keys begin with chatley_.

Only an account owner or administrator can create a key.

warning

A key is shown once and carries the full permissions of the account that owns it. Never put it in browser code, a mobile app, or a public repository — call the API from your own server and keep the key in server-side configuration.

Send the key​

Attach the key to every request in the Authorization header:

Authorization: Bearer chatley_your_key
Content-Type: application/json

Key type must match the method​

A key is created for one HTTP method. Both Developer API endpoints are POST, so a key created as anything other than POST is rejected with METHOD_NOT_ALLOWED_FOR_KEY. If your calls fail that way, create a new key with the POST type rather than changing your request.

Error responses​

Authentication failures return "success": false, an error you can show a developer, and a stable code you can branch on:

{
  "success": false,
  "error": "API key not found or inactive",
  "code": "API_KEY_NOT_FOUND"
}
StatusCodeWhat went wrong
401INVALID_API_KEYThe Authorization header is missing, is not a Bearer token, or the key is not a well-formed Chatley key.
401API_KEY_NOT_FOUNDThe key does not exist, or it has been deactivated in the dashboard.
401API_KEY_EXPIREDThe key is past the expiry date it was created with.
403METHOD_NOT_ALLOWED_FOR_KEYThe key was created for a different HTTP method than the request uses.
500AUTH_ERRORChatley could not verify the key. Retry; if it persists, contact support.

Rotating a key​

Create the replacement key first, deploy it, then deactivate the old one from Integrations & API Keys → API Keys. A deactivated key starts failing immediately with API_KEY_NOT_FOUND, so rotating in that order avoids a gap where your integration cannot call Chatley.

Each key records when it was last used, which makes it easy to confirm nothing is still calling with the old one before you deactivate it.