Authentication and scopes
API keys
Create a key at Settings → API keys. A key starts with alo_live_ followed by 43 base64url characters. Send it only in the HTTPS authorization header:
Authorization: Bearer YOUR_API_KEYThe secret is shown once. Alloglot stores a keyed hash, not the original secret. A key belongs to one reader and opens only the API and MCP server. It does not sign in to app pages or inherit admin access. The account must be email-confirmed and must not be banned or deleted.
Scopes
| Scope | Access |
|---|---|
books:read | List and export your own books, and read story status. A status read can start an audiobook already requested at creation. |
account:read | Read your balance and quote a story. |
levels:read | Read your effective language level labels and recorded native languages. No books, reading history, billing or profile details. |
stories:write | Create stories and request audiobooks, spending your credits. |
Choose only what your integration needs. An assistant that creates and follows stories needs books:read, account:read and stories:write. A shelf exporter needs only books:read.
Language levels
Use levels:read for GET /api/v1/levels. It costs 0 credits and cannot spend or change levels. Existing keys do not gain the scope automatically. For a levels-only integration, choose this scope and a credit cap of zero.
curl --fail-with-body 'https://app.alloglot.com/api/v1/levels?languages=en,es,ja' \
-H "Authorization: Bearer $ALLOGLOT_API_KEY"The optional languages query is one comma-separated list of canonical codes. Omit it to get recorded languages. Unknown codes, aliases, unknown parameters, repeated parameters and empty lists return 400.
Each entry has code, status, displayLevel, native and explanationUrl. The response includes calculatedAt. Keep displayLevel as a string. Native and unavailable levels are null, not zero. Levels are reading estimates, not proficiency certifications.
The explanation pages are a separate release in #2807. Their URLs can return 404 until that guide is approved and deployed. A levels MCP tool is not offered.
OAuth connections
For clients that support it, connect by OAuth instead of copying a key. Sign in on Alloglot's consent page, review requested scopes and set a monthly credit cap. Revoke the connection from the same API keys settings page.
Discovery is at https://app.alloglot.com/.well-known/oauth-authorization-server. Protected-resource discovery is at /.well-known/oauth-protected-resource/api/mcp and /.well-known/oauth-protected-resource/api/v1 on the app host. OAuth uses dynamic public-client registration at /api/oauth/register, authorization at /oauth/authorize, tokens at /api/oauth/token and revocation at /api/oauth/revoke.
Authorization-code flow requires PKCE S256 and an exactly registered redirect URI. Codes last 10 minutes and are single use. Access tokens begin alo_oat_ and last 1 hour. Refresh tokens begin alo_ort_ and last 30 days. Refresh rotates the token. Reusing a code or refresh token revokes the whole connection. Store each new token pair atomically and never refresh concurrently with the same token.
OAuth tokens have the same scopes, credit cap and per-request checks as keys. They do not grant direct database access. OAuth protocol errors use OAuth fields such as error_description, rather than the REST API's {error, code} shape.
Revoke and replace
Revoke a key or connection in Settings → API keys. Revocation is checked on every request. For a suspected leak, revoke first, make a new key with only needed scopes, and replace it in your secret store. Never paste a key into a chat, issue, screenshot or support message.
Keep keys server-side. Do not ship them in browser JavaScript, mobile bundles or URLs. For a personal desktop assistant, use the client's private credential storage or environment support. Never share one reader's key with other people.