Skip to main content

Authentication

Alkax uses different credentials for people using the app and projects integrating from a server. Use the narrowest credential and scopes that fit the workflow.

User sessions​

Interactive user actions use a bearer access token:

Authorization: Bearer <access-token>

Tokens can be issued after supported sign-in methods such as password, passkey, or an enabled identity provider. User sessions are for actions performed on behalf of that user.

Do not copy a user token into a long-running server integration.

Developer Platform credentials​

Server-to-server endpoints accept a project credential:

X-Alkax-Key: ak_test_<key-id>.<secret>

Every project has separate Sandbox and Production environments:

  • Sandbox keys start with ak_test_.
  • Production keys start with ak_live_.

The Free plan can issue and use Sandbox credentials. A paid subscription is required to issue, rotate, or use Production credentials. Monthly API usage is shared across every project and environment billed to the subscription owner.

The full secret is displayed only when the credential is issued or rotated. Store it immediately in a secret manager. Alkax retains the key identifier and a derived secret hash, not the original secret.

Available initial scopes are:

  • places:read
  • geocode:read
  • delivery:read
  • delivery:write

Issue separate credentials for each service and environment. Rotation creates a replacement so you can deploy it before revoking the previous credential. Revocation, expiry, project suspension, and environment suspension invalidate subsequent requests.

See the Developer Platform guide for project setup, Sandbox fixtures, logs, quotas, and webhooks.

Credential safety​

  • Never embed project credentials in frontend JavaScript or a mobile binary.
  • Never put a credential, recipient link, or webhook signing secret in a URL.
  • Redact secrets and private delivery data from logs and traces.
  • Treat 401 as a missing, malformed, invalid, expired, or revoked credential. Treat 403 as an authenticated request without permission for that operation.
  • Revoke a credential immediately if it may have been exposed.
  • Include the response X-Request-Id when contacting support; do not send the credential itself.

The API reference identifies the authentication scheme for each supported endpoint.