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

# Authentication

> Set up API keys or OAuth to access the Annie API

The Annie API supports two authentication methods: API Keys for simple integrations and OAuth for more complex server-to-server setups.

## API Keys

API keys are long-lived tokens ideal for getting started quickly. Generate them from the Developer Portal in your organization settings.

### Using API Keys

Include your API key in the `Authorization` header with the `Bearer` prefix:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer annie-sk-v2-xxxxx" \
    https://api.helloannie.com/v1/bots
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.helloannie.com/v1/bots", {
    headers: {
      "Authorization": "Bearer annie-sk-v1-xxxxx"
    }
  })
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.helloannie.com/v1/bots",
      headers={"Authorization": "Bearer annie-sk-v1-xxxxx"}
  )
  ```
</CodeGroup>

API keys are prefixed with `annie-sk-v1-` so you can easily identify them.

<Warning>
  Keep your API keys secure. Don't commit them to version control or expose them in client-side code.
</Warning>

## OAuth 2.0

OAuth tokens are short-lived access tokens generated using the Client Credentials flow. Use OAuth when you need scoped permissions or are building a production integration.

### Creating an OAuth Client

Create OAuth clients from the Developer Portal on your organization page. You'll receive:

* `client_id` — Your OAuth client identifier
* `client_secret` — Your OAuth client secret (store securely)

### Generating a Token

Request an access token from the Annie OAuth endpoint:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://annie-external-api.us.auth0.com/oauth/token \
    -H "Content-Type: application/json" \
    -d '{
      "grant_type": "client_credentials",
      "client_id": "your-client-id",
      "client_secret": "your-client-secret",
      "audience": "https://api.helloannie.com"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://annie-external-api.us.auth0.com/oauth/token", {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: "your-client-id",
      client_secret: "your-client-secret",
      audience: "https://api.helloannie.com"
    })
  })

  const { access_token } = await response.json()
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://annie-external-api.us.auth0.com/oauth/token",
      json={
          "grant_type": "client_credentials",
          "client_id": "your-client-id",
          "client_secret": "your-client-secret",
          "audience": "https://api.helloannie.com"
      }
  )

  access_token = response.json()["access_token"]
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400
}
```

### Using OAuth Tokens

Include the access token in the `Authorization` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
    https://api.helloannie.com/v1/bots
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.helloannie.com/v1/bots", {
    headers: {
      "Authorization": "Bearer eyJhbGciOiJSUzI1NiIs..."
    }
  })
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.helloannie.com/v1/bots",
      headers={"Authorization": "Bearer eyJhbGciOiJSUzI1NiIs..."}
  )
  ```
</CodeGroup>

Tokens expire after 24 hours. Request a new token when the current one expires.

***

<Card title="Quickstart" icon="rocket" href="/overview/quickstart">
  Ready to build? Follow the quickstart to create your first agent.
</Card>