Skip to main content
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: 
curl -H "Authorization: Bearer annie-sk-v2-xxxxx" \
  https://api.helloannie.com/v1/bots

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

import requests

response = requests.get(
    "https://api.helloannie.com/v1/bots",
    headers={"Authorization": "Bearer annie-sk-v1-xxxxx"}
)
API keys are prefixed with annie-sk-v1- so you can easily identify them.
Keep your API keys secure. Don’t commit them to version control or expose them in client-side code.

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

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()

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"]
Response: 
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400
}

​
Using OAuth Tokens

Include the access token in the Authorization header: 
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  https://api.helloannie.com/v1/bots

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

import requests

response = requests.get(
    "https://api.helloannie.com/v1/bots",
    headers={"Authorization": "Bearer eyJhbGciOiJSUzI1NiIs..."}
)
Tokens expire after 24 hours. Request a new token when the current one expires.

Quickstart

Ready to build? Follow the quickstart to create your first agent.