> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> The three authentication schemes and how to create, use, and revoke a service-account token.

Every authenticated request carries an `Authorization: Bearer <token>` header. Solya
accepts three kinds of bearer token.

## The three schemes

| Scheme                    | Who uses it                                         | Token                                                   |
| ------------------------- | --------------------------------------------------- | ------------------------------------------------------- |
| **BearerAuth**            | The web app (human users) and external integrations | A NextAuth session token **or** a service-account token |
| **Service-account token** | Programs, scripts, AI agents                        | An opaque `solya_sa_…` token (a kind of BearerAuth)     |
| **InternalBearerAuth**    | Internal services / cron only                       | A 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

<Steps>
  <Step title="Open API tokens">
    Go to **Settings → API tokens** (requires an admin permission).
  </Step>

  <Step title="Configure it">
    Give it a name, select the permissions it needs, and optionally an expiry.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Use it">
    Send it as a bearer token (see below).
  </Step>
</Steps>

### Use a token

```bash theme={null}
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:

```bash theme={null}
curl https://app.solya.app/api/auth/whoami \
  -H "Authorization: Bearer solya_sa_…"
```

For a service-account token the response includes:

```json theme={null}
{
  "authKind": "api-token",
  "organizationId": "…",
  "organizationName": "…",
  "effectivePermissions": ["inventoryPlans.view", "analytics.view"],
  "tokenId": "…",
  "tokenName": "My integration",
  "tokenExpiresAt": "2026-12-31T23:59:59.000Z"
}
```

<Warning>
  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.
</Warning>