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:
ScopeAccess
read_writeWork item and queue operations — required for all standard oi CLI commands.
adminSuperset scope that includes all read_write access plus instance admin endpoints.
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: 
POST /me/pats

{
  "name": "local cli",
  "scope": "read_write"
}

​
Use a PAT with the CLI

Configure your oi profile with your token: 
oi profile set --token "oi_pat_..."
Alternatively, set the OPENINDEX_TOKEN environment variable to override the profile value without modifying your config file: 
export OPENINDEX_TOKEN="oi_pat_..."
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: 
Authorization: Bearer oi_pat_...

curl -X GET "https://app.openindex.dev/me" \
  -H "Authorization: Bearer oi_pat_..."

​
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

GET /me/pats
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: 
oi settings personal tokens list
oi settings personal tokens create --name "local cli" --scope read_write

​
Error handling

StatusMeaningResolution
401 UnauthorizedToken is missing, invalid, or revoked.Check the token value with oi auth check or oi profile show.
403 ForbiddenToken scope is insufficient for the requested operation.Use a token with a higher scope — for example, admin for instance admin endpoints.
Run oi auth check to inspect your token’s validity and effective scope: 
oi auth check

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