Authentication

Every request to Spiral carries a short-lived access token that says who is making it. How you get that token depends on who you are. A person runs spiral login once, and the CLI and Python client reuse that sign-in. A pipeline, CI job, or service signs in as a workload with an identity its platform already gives it, so there is no password or API key to store. And when you build an application on Spiral, its users sign in through it as an Application, and the application gets a token that acts for each user.

All three paths end the same way: a bearer token in the Authorization header.

Authorization: Bearer <access-token>

Authentication only proves who the caller is. Authorization decides what that caller can do.

Three ways to sign inCopy Anchor Link

The identity that a token names is called a principal. Spiral has three kinds:

A user belongs to one or more Organizations. A workload belongs to one Project.

People sign in with a device sign-in: the CLI shows a code and opens a browser page, you confirm the code, and the CLI receives the tokens. It caches them and renews them before they expire, so you sign in once per computer. See Sign in.

Workloads have no browser and no password. A workload sends Spiral a token from the platform that runs it, such as GitHub Actions or Kubernetes, or an assertion it signs with its own private key. Spiral checks it against the trust policies and public keys stored on the workload. See How a workload signs in.

Applications send the user to Spiral to sign in and approve the scopes the application asks for. The application then gets a token that acts as that user. See Sign users in.

How your code finds credentialsCopy Anchor Link

The CLI and Rust SDK use the first available configured credential source in this order. A provider or token supplied directly in code takes precedence:

Automatic discovery of a saved user sign-in in the Rust SDK is in development. Use a bearer token or caller-supplied provider when running SDK code as yourself. If SPIRAL_WORKLOAD_ID is set and the client finds no platform token, authentication fails rather than falling back to a sign-in prompt, so a misconfigured job stops instead of hanging.

The SDK's client configuration keeps the selected credential source when tokens expire. A renewal failure returns an error instead of switching to another identity.

What is in an access tokenCopy Anchor Link

An access token is a signed JWT. Most code never looks inside it, but these claims matter when you build on the HTTP API:

• Subject. The sub claim is the user or workload ID.
• Organization. A user token names one Organization in org_id, and requests apply to that Organization. To work in another one, get a new token for it. See Choose an Organization.
• Audience. The aud claim names the API the token was issued for, and only that API accepts it.
• Expiry. Tokens are short-lived; a user access token lasts at most one hour. Security lists every lifetime.

Spiral publishes its signing keys at https://auth.spiraldb.com/.well-known/jwks.json and its OAuth metadata at https://auth.spiraldb.com/.well-known/oauth-authorization-server, so your application can verify tokens with a standard OAuth or JWT library.

Where it runsCopy Anchor Link

Spiral hosts one authorization server, at https://auth.spiraldb.com, for every deployment. It signs people in and issues every access token. It follows the OAuth 2.0 and OpenID Connect standards, so standard OAuth libraries work with it. Each Spiral service checks a token's signature with the published keys. See Architecture.

EndpointsCopy Anchor Link

The HTTP reference lists every operation. The Workloads API manages workloads, their keys, and their trust policies.

GuidesCopy Anchor Link

• Sign in from the CLI, and get a token for HTTP calls.
• Create a workload for a pipeline or a service.
• Register an Application so your application's users can sign in.