# Authentication | HTTP API AI Autocomplete Docs

> For the complete documentation index, see [llms.txt](https://ai-autocomplete.com/llms.txt). A markdown version of any page on this site is available by appending `.md` to its URL path — the homepage is at `/index.md`.

Authentication guide for integrating the AI Autocomplete SDK with HTTP API. Code examples, setup, and API reference.

Source: https://ai-autocomplete.com/docs/http/authentication

---

Two key types, two integration paths. Pick the one that matches where your code runs.

[Manage your keys](https://ai-autocomplete.com/account/keys)

## Choosing a mode

Public key mode is the fastest path: send the key as a Bearer token and call /api/suggest. Secret key + access token mode is recommended for production — your server holds the secret key, mints short-lived tokens, and the client uses those.

## Public key

Send the public key as a Bearer credential in the Authorization header. Public keys are scoped and rate-limited; they're safe to ship in client-side code.

**curl**

```bash
curl https://api.ai-autocomplete.com/api/suggest \
  -H "Authorization: Bearer pk_v1_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "raw_query": "Create a" }, "meta": { ... } }'
```

Security

Public keys are safe in client bundles, but for production we recommend the secret key + access token flow below — short-lived tokens limit blast radius if a credential leaks. Never put a secret key in client code.

## Secret key + access token (recommended)

Keep the secret key on your server. Your server exchanges it for a short-lived access token, which your client passes as a Bearer credential when calling /api/suggest.

### Mint a token

On your backend, exchange the secret key for a short-lived access token. Forward the response to your client — the secret key must never reach end-user devices.

POST `https://api.ai-autocomplete.com/api/auth/token`

Headers

`Authorization: Bearer <sk_v1_…>` — your secret key.

Body

`product_id` — the UUID of the product the token is for. Visible in the URL of the product editor at /edit.

Request body

```json
{
  "product_id": "<uuid>"
}
```

200 OK

```json
{
  "access_token": "at_v1_AbCdEfGh...",
  "expires_at": 1775464738,
  "token_type": "Bearer"
}
```

expires_at is unix seconds. Pass it through unchanged — the SDK normalizes it.

401 Unauthorized

```json
{
  "error": {
    "code": "INVALID_SECRET_KEY",
    "message": "The provided secret key is invalid"
  }
}
```

### Use the token

Call /api/suggest with the returned access_token in the Authorization header.

**curl**

```bash
# Mint a short-lived access token on your server
TOKEN_JSON=$(curl -s https://api.ai-autocomplete.com/api/auth/token \
  -H "Authorization: Bearer $MAGICX_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "product_id": "<your-product-id>" }')

ACCESS_TOKEN=$(echo "$TOKEN_JSON" | jq -r .access_token)

# Call /api/suggest with the access token
curl https://api.ai-autocomplete.com/api/suggest \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "raw_query": "Create a" }, "meta": { ... } }'
```

How refresh works

Tokens have a short TTL. Refresh proactively at least 30 seconds before expires_at, and on a 401 force-refresh once and retry the original request. See Advanced for caching and retry patterns.