Skip to main content
Every authenticated request carries an Authorization: Bearer <token> header. Solya accepts three kinds of bearer token.

​
The three schemes

SchemeWho uses itToken
BearerAuthThe web app (human users) and external integrationsA NextAuth session token or a service-account token
Service-account tokenPrograms, scripts, AI agentsAn opaque solya_sa_… token (a kind of BearerAuth)
InternalBearerAuthInternal services / cron onlyA static server-side token — not user-creatable
For integrations you’ll use a service-account token. It is validated on the same Authorization: Bearer header as a user session, so the same endpoints work for both.

​
Service-account tokens

A service-account token represents an organization, not a person, and carries an explicit set of permissions.
  • Format — solya_sa_ followed by 43 URL-safe characters (≈ 52 characters total), backed by 256 bits of entropy.
  • Storage — Solya stores only a SHA-256 hash. The plaintext token is shown once at creation and never again — copy it immediately into your secret manager.
  • Permissions — fixed at creation. The token can do only what its permissions allow (the same permission model as roles — e.g. inventoryPlans.view, analytics.view, dataPlatform.configure).
  • Expiry — optional, up to 365 days; you can also choose “never expires”.
  • Limit — up to 50 active tokens per organization.

​
Create a token

1

Open API tokens

Go to Settings → API tokens (requires an admin permission).
2

Configure it

Give it a name, select the permissions it needs, and optionally an expiry.
3

Copy the plaintext once

Copy the solya_sa_… value immediately and store it securely. You won’t be able to see it again — only its last characters are shown afterwards.
4

Use it

Send it as a bearer token (see below).

​
Use a token

curl https://app.solya.app/api/brands \
  -H "Authorization: Bearer solya_sa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

​
Revoke a token

Revoke a token from Settings → API tokens at any time — revocation is immediate. Tokens are also revoked automatically if the user who created them is removed from the organization.

​
Check who you are

Call GET /api/auth/whoami to confirm a token is valid and see its effective access: 
curl https://app.solya.app/api/auth/whoami \
  -H "Authorization: Bearer solya_sa_…"
For a service-account token the response includes: 
{
  "authKind": "api-token",
  "organizationId": "…",
  "organizationName": "…",
  "effectivePermissions": ["inventoryPlans.view", "analytics.view"],
  "tokenId": "…",
  "tokenName": "My integration",
  "tokenExpiresAt": "2026-12-31T23:59:59.000Z"
}
Treat solya_sa_… tokens like passwords. Never commit them to source control or paste them into logs. Rotate them before expiry and revoke any token you suspect is exposed.