Skip to main content
OpenIndex uses Personal Access Tokens (PATs) as bearer tokens for all API and CLI authentication. There are no session cookies or OAuth flows for programmatic access — every request carries a PAT.

​
Token scopes

PATs are issued with one of two scopes: Use read_write for agents and automation. Reserve admin tokens for administrative tooling.

​
Create a PAT

Create tokens in the OpenIndex web UI:
  1. Sign in to the web UI.
  2. Navigate to Settings → Personal → Tokens.
  3. Click Create token, enter a name, and choose a scope.
  4. Optionally set an expiry date. If you leave the expiry blank, the token does not expire.
  5. Copy the token value — it begins with oi_pat_ and is shown only once.
The token value is displayed only at creation time. Store it in a secrets manager or environment variable before leaving the page.
You can also create tokens via the API:

​
Use a PAT with the CLI

Configure your oi profile with your token:
Alternatively, set the OPENINDEX_TOKEN environment variable to override the profile value without modifying your config file:
The environment variable takes precedence over the profile token when both are set.

​
Use a PAT with the HTTP API

Pass the token as a bearer token in the Authorization header:

​
PAT lifetime

PATs are non-expiring by default. When you create a token, you can optionally set an expiry date. After the expiry date, the token is rejected with a 401 Unauthorized response. To rotate a token, create a new one and delete the old one.

​
Manage PATs via API

Returns all PATs for the authenticated user, including token names, scopes, and expiry dates. Token values are not included in list responses.
You can also manage tokens from the CLI:

​
Error handling

Run oi auth check to inspect your token’s validity and effective scope:

​
Security notes

Workflow agent run tokens are intentionally rejected for settings commands. Use a human-owned PAT — not a workflow agent run token — when running oi settings ... commands or any admin endpoint.
Store PATs in environment variables or a secrets manager rather than committing them to source code or config files. Use separate tokens for separate environments so you can revoke them independently.