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

# Authentication

> An org API token for programs, a member session for the console.

There are two ways into an org. A **program** (a script, the `litmus-ai` CLI,
your own agent) uses an **org API token**. A **person** signs into the console
with a **member session**. The two reach the same routes, the ones in this
reference.

## Org API tokens

An org admin mints a token on the org's settings page in the console. An
existing `admin` token can also mint one with
[`POST /v0/orgs/{orgtag}/tokens`](/reference/org). A token:

* starts with `litk_` and belongs to **one org**. It can never reach another
  org's data, whatever route it is sent to.
* has a **scope**, and each scope includes the one below it:

  | Scope | What it adds |
  | - | - |
  | `read` | every `GET` in this reference |
  | `push` | pushing evidence, starting pipelines and runs, writing sandboxes |
  | `admin` | tokens, members, and the org-level settings |

  Each route's page lists the scope it needs.
* is **shown once**, in the response that creates it. The workspace stores only
  a hash of it, so a lost token cannot be recovered. Mint a new one and revoke
  the old one.
* can carry an expiry, and can be revoked at any time with
  [`DELETE /v0/orgs/{orgtag}/tokens/{tid}`](/reference/org).

### Using a token

Keep the token in an environment variable, never in a file you commit, a URL,
or a chat message. Every example in this reference reads three variables:

| Variable | Holds |
| - | - |
| `LITMUS_URL` | your workspace's URL. The CLI defaults to `https://api.litmus.ai` |
| `LITMUS_TOKEN` | your org API token |
| `LITMUS_ORG` | your org's tag, the one your token belongs to |

**Replace the org tag with your own.** Every path in this reference that
holds `{orgtag}` names one org, and every example writes it as `$LITMUS_ORG`:
set that variable to your org's tag (the CLI reads it too), or put your tag in
its place. A token sent to another org's path is refused with `403`.

Send the token as a bearer token:

```bash theme={null}
curl -sS "$LITMUS_URL/v0/whoami" \
  -H "Authorization: Bearer $LITMUS_TOKEN"
```

`GET /v0/whoami` answers with the token's `kind`, `org`, `scope` and `name`,
and never with the token itself. It is the quickest way to check that a token
works.

### When a token is refused

| Status | Means |
| - | - |
| `401` | The token is unknown, revoked, or expired. The body says which, and names the token. |
| `403` | The token is for a different org than the one the path names, or its scope is too low for this route. The body names the mismatch. |
| `404` | The record you named belongs to another org, or does not exist. The two get the same answer on purpose, so a token cannot learn what another org holds. |

A route that is **not** in this reference cannot be called with an org token
at all. It answers `403` and says it needs the workspace's service token, which
belongs to the workspace's operators and is never issued to an org.

## Member sessions

A member is a person invited to the org, who signs into the console. The
console checks the membership, then calls the same routes in this reference on
the member's behalf. A member who wants to script something mints an org token
(or asks the org's admin for one); the session itself is not an API
credential.

## Sandbox tokens are different

A served sandbox world has its own connector token. It starts with `lit_`,
opens one world's MCP endpoint and nothing else, and is minted with
[`POST /v0/tokens`](/reference/sandboxes). See [MCP](/mcp).


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