API Authentication

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

Scope	Access
`read_write`	Create, read, update, and delete work items, domains, workflows, calendar sources, and conversation resources.
`admin`	All `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

string

required

A display name to identify this token (e.g. ci-pipeline, agent-alpha).

string

required

Token scope: read_write or admin.

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"
  }'

oi settings personal tokens create --name agent-alpha --scope read_write

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>"
}

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

Overview

Work Items

Integrations

API Authentication

Token scopes

Create a token

List tokens

Delete a token

Claim an invite

Using your token with the `oi` CLI

​Token scopes

​Create a token

​List tokens

​Delete a token

​Claim an invite

​Using your token with the oi CLI

Token scopes

Create a token

List tokens

Delete a token

Claim an invite

Using your token with the `oi` CLI