Skip to main content
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. 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: 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}.

​
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: 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:
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

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. See MCP.