api

Authentication

The Roxels REST API authenticates with bearer tokens. There are two kinds of keys.

Key types

Secret keys (`sk_…`)

Server-side only. Never put one in a browser.
Grant full access to your org's templates, conversations, persons, and webhook secrets.
Use these from your backend.

Embed keys (`rk_…`)

Safe to ship to the browser.
Domain-allowlisted: only origins you specify can use them.
Scoped to a single template — they can start a session for that template and nothing else.
Use these in the embed.

If you're not sure which to use: server code uses sk_, browser code uses rk_.

Generating a key

Sign in at app.roxels.ai.
Open Settings → API Keys.
Click Generate.
Copy the key. It's shown once. If you lose it, generate a new one.

For embed keys, generate them from the template's embed settings instead — they're scoped to the template and require a domain allowlist.

Authenticating a request

Pass the key as a bearer token:

curl https://api.roxels.ai/v1/templates \
  -H "Authorization: Bearer sk-your-key-here"

In JavaScript:

const res = await fetch("https://api.roxels.ai/v1/templates", {
  headers: {
    Authorization: `Bearer ${process.env.ROXELS_API_KEY}`,
  },
});

In Python:

import os, httpx
r = httpx.get(
    "https://api.roxels.ai/v1/templates",
    headers={"Authorization": f"Bearer {os.environ['ROXELS_API_KEY']}"},
)

Storing keys safely

Never commit keys to git. Use environment variables or a secrets manager.
Never log keys. Logging libraries that capture request headers can leak them.
Never share keys between orgs or environments. Each environment should have its own.
Rotate keys when an engineer leaves or a key may have been exposed. Revoking + generating a new one is instant.

Revoking a key

From the dashboard at Settings → API Keys, click the key and revoke it. The next request authenticated with that key returns 401 Unauthorized.

Test vs production

There's one API for both. Use separate API keys (and ideally separate orgs) for non-production environments so test data doesn't co-mingle with production records.

Error responses

Status	Meaning
`401 Unauthorized`	No bearer token, malformed token, or revoked key.
`403 Forbidden`	The key is valid but doesn't have permission for this resource.
`404 Not Found`	The resource doesn't exist (or doesn't exist for this org).
`429 Too Many Requests`	Rate-limit exceeded; back off and retry.

See Pagination and errors for response shapes.