Skip to content
Apolaris AI Docs

Personal API tokens

developer

Create, scope and revoke bearer tokens for the REST API from your account.

A personal API token is a long random secret that lets a script, scheduled job, or third-party integration call the Apolaris AI REST API on your behalf — without driving a browser session or sharing your password. You create and revoke your own tokens from your account page; no administrator has to issue them.

The most important thing to understand: a token acts as you. It inherits your organization, your visible sites, and your can_* privileges, so it can never do more through the API than your account can do in the app.

Who can do this

Any signed-in user with a CRM profile can manage their own tokens — this is a self-service account feature, not a privileged one. There is no separate privilege to "create tokens"; what the token can do is governed entirely by the privileges your account already has.

Action Who Notes
Create / revoke your own tokens Any user with an account Self-service, no extra privilege needed
What a token can read/write Governed by your can_* privileges A non-manager token is limited to its grants
See another user's tokens No one (self-service only) You only ever see and manage your own list

A platform-operator account with no CRM profile has nothing to manage here. Day-to-day org users always have a profile and see the tokens page.

Where to create a token

  1. Open your account profile, then go to Account → API tokens. The page lives at /customers/account/api-tokens/.
  2. Under Personal access tokens, type an optional Token name to recognise it later (for example Reporting script or Zapier).
  3. Click Generate token.

The new token appears at the top of the page under Token created, with a Copy button.

The raw token is shown once, at creation, and never again. Only a SHA-256 hash of it is stored, so even an administrator or a database leak cannot recover the secret. Copy it immediately and put it in a secret manager. If you lose it, you cannot retrieve it — revoke it and generate a new one.

A raw token always starts with the prefix ztk_ and looks like:

ztk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

In your token list, only the first few characters (the prefix, e.g. ztk_AbCd…) are ever displayed — enough to tell two tokens apart without exposing either secret.

Use the token

Send the token in the Authorization header as a bearer token on every request:

# Minimal smoke test — confirm the token works and see who it acts as
curl -H "Authorization: Bearer ztk_your_token_here" \
     https://your-domain/api/v1/me/

GET /api/v1/me/ returns your identity, your is_manager flag, and your visible site ids — the quickest way to confirm a token is valid and to see exactly what it is scoped to. For the full endpoint reference, base URL, pagination, and error format, see the REST API overview.

X-API-Key: ztk_… is accepted as a fallback header if a tool cannot set Authorization. Prefer Authorization: Bearer where you can.

What a token can and cannot do

A token is not independently scoped — there is no separate "scopes" or "permissions" picker. It simply borrows your account's access at the moment of each call:

  • Organization (tenant): every call is scoped to your organization. A token can never read or write another organization's data.
  • Visible sites: if you are not a manager, the token sees only the sites you can see — your employee's sites plus any explicit grants. A manager (is_manager) token sees all sites in the organization.
  • Privileges: reads require your matching can_view_* privilege and writes require the matching add/edit privilege. Because the token can never exceed your account, the safest way to limit an integration is to run it from a user account that has only the privileges that integration needs.

Because access is borrowed live, changing your privileges or your visible sites immediately changes what every one of your tokens can do — there is no need to re-issue them. Likewise, if your account is disabled, all of your tokens stop working.

Example: a least-privilege reporting integration

Suppose you want a nightly dashboard that only reads sales. Rather than minting a token on an owner account (which could write everything), create a dedicated user whose only privilege is can_view_sale, sign in as that user, and generate the token there. The token can pull GET /api/v1/sales/ but is incapable of creating bookings, editing customers, or touching another site — because the user behind it cannot either.

Track usage

Each authenticated call stamps the token's last used time. Your token list shows Name, Prefix, Created, Last used (or never), and Status (Active / Revoked) — so you can spot tokens that are still live and ones that have gone idle.

Revoke a token

  1. On the API tokens page, find the token under Your tokens.
  2. Click Revoke and confirm.

Revocation is immediate and a soft delete: the token stops authenticating at once (the next call gets 401 unauthorized), but the row stays in your list with a Revoked status for the audit trail. There is no way to un-revoke; mint a new token if you need access again.

Revoking a token breaks every integration using it — the scheduled job, webhook caller, or third-party connector that holds it will start failing immediately. Roll the replacement token into those tools before you revoke the old one. If you suspect a token has leaked, revoke first and re-issue after; a leaked active token can do anything your account can.

Good practices

- Give each integration its own named token, so you can revoke one without disrupting the others and tell from Last used which is which. - Treat tokens like passwords: store them in a secret manager, never commit them to version control, and never embed them in client-side code. - Rotate periodically — generate the new token, switch your integration over, confirm it works, then revoke the old one. - Run automations from a least-privilege user account rather than an owner/manager account, since the token inherits whatever that user can do.

REST API overview API examples