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

# API Keys

> Generate and manage Personal Access Tokens for the Raydocs API

Personal Access Tokens are the credentials you use to authenticate with the Raydocs REST API. They're scoped, revocable, and tied to your user account — **keep them secret**.

## Creating a Token

<Steps>
  <Step title="Sign In">
    Sign in to your Raydocs account at [raydocs.com](https://raydocs.com).
  </Step>

  <Step title="Open Settings">
    Click on your profile icon and select **Settings**, then navigate to
    **Access Tokens**.
  </Step>

  <Step title="Create New Token">
    Click **Create new token** and enter a descriptive name (e.g.,
    "Production Integration").
  </Step>

  <Step title="Select Abilities">
    Choose the abilities (scopes) you want to grant to this token.
  </Step>

  <Step title="Copy Token">
    Click **Create** and copy the token value immediately.

    <Warning>
      You won't be able to see the token again after closing the dialog.
      Store it securely.
    </Warning>
  </Step>
</Steps>

## Abilities

Abilities control what operations a token can perform:

| Ability                     | Grants                                             |
| --------------------------- | -------------------------------------------------- |
| `workspaces-read`           | List workspaces                                    |
| `workspaces-write`          | Create, update or delete workspaces                |
| `workspace-users-read`      | List members and invites                           |
| `workspace-users-write`     | Manage members and invites                         |
| `documents-read`            | List documents and generate signed download URLs   |
| `documents-write`           | Create, update, or delete documents                |
| `workflows-read`            | List workflows and workflow runs                   |
| `workflow-runs-output-read` | Read public workflow run outputs                   |
| `templates-read`            | List and view extraction templates                 |
| `templates-write`           | Create, update, or delete templates                |
| `sessions-read`             | List sessions, documents, and results              |
| `sessions-write`            | Create sessions, upload documents, run extractions |

<Tip>
  Choose the minimum set of abilities your integration requires. This follows
  the principle of least privilege and limits exposure if a token is
  compromised.
</Tip>

For the Raydocs Windows synchronization client, use the dedicated preset in the token modal. It scopes the token to the current workspace and selects only `workspaces-read`, `workflows-read`, `workflow-runs-output-read`, and `documents-read`.

## Using the Token

Send the token in the `Authorization` header with every API request:

```http theme={null}
Authorization: Bearer <access_token>
```

### Example

```bash theme={null}
curl -X GET "https://api.raydocs.com/workspaces" \
  -H "Authorization: Bearer rd_live_abc123xyz..."
```

## Revoking a Token

If a token is leaked or no longer needed:

<Steps>
  <Step title="Go to Settings">
    Navigate to **Settings → Access Tokens**.
  </Step>

  <Step title="Find Token">
    Locate the token you want to revoke in the list.
  </Step>

  <Step title="Revoke">Click **Revoke** next to the token.</Step>
</Steps>

Any API requests using a revoked token will receive `401 Unauthorized`.

## Best Practices

<AccordionGroup>
  <Accordion title="Secure Storage">
    Store tokens in environment variables, secret managers (AWS Secrets
    Manager, HashiCorp Vault), or CI/CD secrets. Never hardcode tokens in
    source code. `bash # Good: Environment variable export
                RAYDOCS_API_TOKEN="rd_live_abc123..." # In your code token =
                os.environ.get("RAYDOCS_API_TOKEN") `
  </Accordion>

  <Accordion title="One Token Per Integration">
    Create a dedicated token for each integration or service. This makes it
    easy to revoke access for a single integration without affecting others.
  </Accordion>

  <Accordion title="Avoid Version Control">
    Never commit tokens to Git or other version control systems. Add token
    files to `.gitignore` and use secret scanning tools. `gitignore #
                .gitignore .env .env.local secrets.json `
  </Accordion>

  <Accordion title="Regular Rotation">
    Rotate tokens periodically, especially for production integrations.
    Create a new token, update your integration, then revoke the old token.
  </Accordion>

  <Accordion title="Minimal Scope">
    Only grant the abilities your integration actually needs. A read-only
    dashboard integration shouldn't have write permissions.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    **Possible causes:** - Token is missing from request - Token has been
    revoked - Token is malformed **Solution:** Verify the token is included
    correctly in the `Authorization` header and hasn't been revoked.
  </Accordion>

  <Accordion title="403 Forbidden">
    **Possible causes:** - Token lacks required ability for the endpoint -
    Attempting to access a resource in another workspace **Solution:** Check
    that your token has the necessary abilities for the operation you're
    attempting.
  </Accordion>
</AccordionGroup>