Skip to content

Authentication

Every request to the Elaichi API carries an API token in the Authorization header:

Authorization: Bearer $ELAICHI_API_TOKEN

A token looks like elch_<organization id>_<secret>. It belongs to one organization and to the person who created it. Requests run with that person’s permissions, so a token can never do more than that person can.

Create a token

Only a person in the app can create a token.

  1. Sign in at app.elaichi.ai and switch to the organization you want to automate.
  2. Open Settings → API tokens.
  3. Click Create API token.
  4. Name the token after where you will use it, such as CI pipeline.
  5. Confirm it’s you when Elaichi asks.
  6. Copy the token. Elaichi shows it once and cannot show it again.
  7. Store it in a password manager or secret store, never in source control.

The Create API tokens guide describes the same screen in more detail.

Make a request

curl https://api.elaichi.ai/connection \
  -H "Authorization: Bearer $ELAICHI_API_TOKEN"

Keep the token in an environment variable, not in your scripts.

Choose the organization

A token already names its organization, so you do not need to send X-Organization-Id. If you send it, the value must match the organization of the token. A different value returns 403.

Permissions

Most endpoints that change something need a specific permission. The permissions come from the roles of the person who created the token.

  • If you change that person’s roles, the token’s access changes right away.
  • If you revoke the token, access ends right away.
Response Meaning
401 unauthorized The token is missing, wrong, or revoked.
403 permission_required The token is valid, but the person who created it lacks a permission. The error’s details.required_permissions lists the permissions. Check the person’s role in Settings → People.
403 forbidden The action is not allowed for this token. For example, it needs a person in a browser.

What a token cannot do

An API token cannot manage tokens. Every /api-token and /scim-token endpoint answers 403 to a token. A token also cannot approve or reject an access request, schedule the deletion of an organization, or change whether the organization requires two-factor authentication. Do these in the app.

Revoke a token

Open Settings → API tokens and choose Revoke for the token. Elaichi asks you to confirm it’s you. Revoking takes effect right away and cannot be undone. Create a new token and update your integration.

If a token might have leaked, revoke it first and create a replacement second.