> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca.0-9.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication

> Authenticate API requests with Personal Access Tokens.

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

<Warning>
  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.
</Warning>

## Create a token

```bash theme={null}
POST /me/pats
Authorization: Bearer <existing-pat>
Content-Type: application/json
```

<ParamField path="body.name" type="string" required>
  A display name to identify this token (e.g. `ci-pipeline`, `agent-alpha`).
</ParamField>

<ParamField path="body.scope" type="string" required>
  Token scope: `read_write` or `admin`.
</ParamField>

<ParamField path="body.expiresAt" type="string">
  Optional ISO 8601 expiry date (e.g. `2026-12-31T23:59:59Z`). If omitted, the token does not expire.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```bash oi CLI theme={null}
  oi settings personal tokens create --name agent-alpha --scope read_write
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "id": "pat_01abc123",
  "name": "agent-alpha",
  "scope": "read_write",
  "token": "oi_pat_...",
  "expiresAt": "2027-01-01T00:00:00Z",
  "createdAt": "2026-03-31T10:00:00Z"
}
```

<Warning>
  The full token value is only returned at creation time. Store it securely — you cannot retrieve it again.
</Warning>

## List tokens

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
POST /auth/invites/claim
Content-Type: application/json

{
  "token": "<invite-token>"
}
```

<ParamField path="body.token" type="string" required>
  The invite token from your invite link or email.
</ParamField>

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:

```bash theme={null}
oi profile set \
  --app-url "https://your-deployment.convex.site" \
  --token "oi_pat_..." \
  --agent-id "agent-alpha"
```

Verify connectivity:

```bash theme={null}
oi auth check
```