Skip to main content
OpenIndex uses Personal Access Tokens (PATs) to authenticate API requests. Include your token as a Bearer token in the Authorization header of every request. 
Authorization: Bearer <your-pat>

​
Token scopes

ScopeAccess
read_writeCreate, read, update, and delete work items, domains, workflows, calendar sources, and conversation resources.
adminAll read_write access plus instance administration: user management, AI provider configuration, email infrastructure, and instance settings.
Use admin-scoped tokens only for administrative operations. Workflow agent run tokens should use read_write scope. Admin tokens cannot be used as agent run tokens for workflow stage dispatch.

​
Create a token

POST /me/pats
Authorization: Bearer <existing-pat>
Content-Type: application/json
​
body.name
string
required
A display name to identify this token (e.g. ci-pipeline, agent-alpha).
​
body.scope
string
required
Token scope: read_write or admin.
​
body.expiresAt
string
Optional ISO 8601 expiry date (e.g. 2026-12-31T23:59:59Z). If omitted, the token does not expire.
curl --request POST \
  --url https://your-deployment.convex.site/me/pats \
  --header 'Authorization: Bearer oi_pat_your_existing_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "agent-alpha",
    "scope": "read_write",
    "expiresAt": "2027-01-01T00:00:00Z"
  }'
Response: 
{
  "id": "pat_01abc123",
  "name": "agent-alpha",
  "scope": "read_write",
  "token": "oi_pat_...",
  "expiresAt": "2027-01-01T00:00:00Z",
  "createdAt": "2026-03-31T10:00:00Z"
}
The full token value is only returned at creation time. Store it securely — you cannot retrieve it again.

​
List tokens

GET /me/pats
Authorization: Bearer <your-pat>
Returns all tokens for your account. Token values are not included in the list response.

​
Delete a token

DELETE /me/pats/:id
Authorization: Bearer <your-pat>
Deletes the token with the given ID. The deleted token is immediately invalidated.

​
Claim an invite

If you received an invite link to join an OpenIndex instance, claim it to activate your account: 
POST /auth/invites/claim
Content-Type: application/json

{
  "token": "<invite-token>"
}
​
body.token
string
required
The invite token from your invite link or email.
This endpoint does not require an existing Bearer token.

​
Using your token with the oi CLI

Store your token in a CLI profile so you do not need to pass it on every command: 
oi profile set \
  --app-url "https://your-deployment.convex.site" \
  --token "oi_pat_..." \
  --agent-id "agent-alpha"
Verify connectivity: 
oi auth check