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

# Authentication

> How to authenticate with the OpenIndex API and CLI using Personal Access Tokens.

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:

| Scope        | Access                                                                              |
| ------------ | ----------------------------------------------------------------------------------- |
| `read_write` | Work item and queue operations — required for all standard `oi` CLI commands.       |
| `admin`      | Superset 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.

<Warning>
  The token value is displayed only at creation time. Store it in a secrets manager or environment variable before leaving the page.
</Warning>

You can also create tokens via the API:

```bash theme={null}
POST /me/pats
```

```json theme={null}
{
  "name": "local cli",
  "scope": "read_write"
}
```

## Use a PAT with the CLI

Configure your `oi` profile with your token:

```bash theme={null}
oi profile set --token "oi_pat_..."
```

Alternatively, set the `OPENINDEX_TOKEN` environment variable to override the profile value without modifying your config file:

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.openindex.dev/me" \
    -H "Authorization: Bearer oi_pat_..."
  ```

  ```javascript fetch theme={null}
  const response = await fetch("https://app.openindex.dev/me", {
    headers: {
      Authorization: "Bearer oi_pat_...",
    },
  });
  ```
</CodeGroup>

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

<Tabs>
  <Tab title="List tokens">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Create a token">
    ```bash theme={null}
    POST /me/pats
    ```

    Request body:

    ```json theme={null}
    {
      "name": "agent-production",
      "scope": "read_write"
    }
    ```

    The response includes the token value. This is the only time the value is returned.
  </Tab>

  <Tab title="Delete a token">
    ```bash theme={null}
    DELETE /me/pats/:id
    ```

    Deleting a token immediately invalidates it. Any in-flight requests using the token will begin receiving `401 Unauthorized` responses.
  </Tab>
</Tabs>

You can also manage tokens from the CLI:

```bash theme={null}
oi settings personal tokens list
oi settings personal tokens create --name "local cli" --scope read_write
```

## Error handling

| Status             | Meaning                                                  | Resolution                                                                           |
| ------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `401 Unauthorized` | Token is missing, invalid, or revoked.                   | Check the token value with `oi auth check` or `oi profile show`.                     |
| `403 Forbidden`    | Token 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:

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

## Security notes

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

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