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

# Authentication

> Token types, scopes, and best practices

export const ScarfPixel = () => <img referrerPolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=831669b6-b4bd-42cb-8832-2122c03e1d5f" alt="" width="1" height="1" style={{
  position: "absolute",
  width: 0,
  height: 0,
  opacity: 0,
  pointerEvents: "none"
}} />;

<ScarfPixel />

## Token types

Strix has two types of API tokens:

### Personal tokens

* Attached to one user
* Expire after 90 days (default)
* Best for individual scripts and local tools

### Service keys

* Org-level, not attached to a user
* Can stay valid for a long time (no default expiry)
* Best for CI/CD pipelines and production integrations
* **Only org admins can create service keys**

## Default scopes

**Service keys** default scopes:

```
scans:read, scans:write, vulnerabilities:read, vulnerabilities:write,
schedules:read, schedules:write, assets:read, webhooks:read, webhooks:write
```

**Personal tokens** default scopes:

```
scans:read, scans:write, vulnerabilities:read, vulnerabilities:write,
schedules:read, schedules:write, assets:read
```

These defaults apply when creating a token from API Access or `POST /api/v1/tokens`. Device login creates a named CLI session with Minimal, Recommended, Full, or Custom access and an immutable login ceiling. It is shown separately from ordinary keys in API Access and reused by later sign-ins from the same CLI installation. See [CLI login](/guides/cli-login).

`webhooks:write` is admin-only. `tokens:write` lets an active member manage ordinary personal tokens; the current CLI session can list/switch its memberships, inspect or narrow itself, and revoke itself without that scope. Its login ceiling prevents switching from widening authority. Only organization admins can create service keys or manage another member's tokens.

You can change the scopes when you create a token.

## Resource-restricted tokens

API `scopes` control what a token may do. With Enterprise RBAC, optional `rbac_scopes` further restrict which assets it may access. Each resource restriction is an object with exactly these fields:

```json theme={null}
{"type": "tag", "value": "payments"}
```

`type` is `target`, `tag`, or `business_unit`; `value` is 1–120 characters and may contain ASCII letters, digits, `.`, `_`, `:`, `/`, `@`, or `-`. A `target` value identifies one asset, while `tag` and `business_unit` values match asset metadata. An empty `rbac_scopes` array means organization-wide asset access within the token's API scopes and the creator's current role. When a token-authenticated caller creates another token and omits `rbac_scopes`, the new token inherits the caller's restrictions. An explicit list must be a subset of the caller token's restrictions. API scopes are similarly capped by the member's current organization role and by the caller token.

The CLI exposes the token request fields directly:

```bash theme={null}
strix cloud tokens create \
  --type personal \
  --name payments-reader \
  --scopes scans:read vulnerabilities:read assets:read \
  --rbac-scopes '[{"type":"tag","value":"payments"}]' \
  --expires-in-days 30
```

Use `--expires-at <ISO-8601>` instead for an absolute expiration. The token secret is returned only by the create response; store it securely before leaving the output.

## Available scopes

Each endpoint specifies the scope that it requires. A token can only call the endpoints that match its scopes.

| Scope | Grants |
| - | - |
| `scans:read` / `scans:write` | View / manage pentests, retests, templates |
| `scans:message` | Send messages to a running pentest |
| `vulnerabilities:read` / `vulnerabilities:write` | View / update findings, history, fix PRs |
| `dependencies:read` | View dependency inventory |
| `supply_chain:read` / `supply_chain:write` | View / update supply-chain alerts |
| `schedules:read` / `schedules:write` | View / manage scheduled scans |
| `assets:read` / `assets:write` | View / manage domains and repositories |
| `pr_reviews:read` / `pr_reviews:write` | View / start PR reviews and settings |
| `connectors:read` / `connectors:write` | View / manage network connectors |
| `knowledge:read` / `knowledge:write` | View / manage org knowledge, policies, settings |
| `integrations:read` / `integrations:write` | View / connect / disconnect SCM integrations |
| `uploads:write` | Request, finalize, and delete file uploads |
| `chat:read` / `chat:write` | View / start chats and send messages |
| `analytics:read` | Read dashboard analytics |
| `llm:read` / `llm:write` | View / update self-hosted LLM settings and usage |
| `test_users:read` / `test_users:write` | View / manage domain test users and inboxes |
| `license:read` | View license details |
| `billing:read` / `billing:write` | View billing / buy credits and manage automatic top-up |
| `organizations:read` / `organizations:write` | View / manage organization settings |
| `members:read` / `members:write` | View / manage members |
| `invitations:read` / `invitations:write` | View / manage invitations |
| `webhooks:read` / `webhooks:write` | View / manage webhooks (write is admin-only) |
| `audit:read` | Read the audit log |
| `tokens:write` | Manage your personal tokens; admins can manage organization tokens and service keys |

## Using tokens

Include the token in the `Authorization` header:

```bash theme={null}
curl -X GET "https://app.strix.ai/api/v1/scans" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"
```

Managed CLI sessions also send `X-Strix-Workspace: <organization_id>` on normal API requests. This pins a process to the workspace it started in and turns a concurrent switch into a safe `409` conflict. Ordinary API tokens do not require this header.

## Best practices

* Give each integration only the scopes that it needs (**least privilege**)
* **Rotate tokens regularly**, especially service keys
* If a token is compromised, **revoke it immediately**. A revoked token stops operation on the next request
* Use **personal tokens** for development and **service keys** for production


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.