---
title: "API authentication"
url: "https://stylome.io/api/docs/authentication"
---

> [Documentation index](https://stylome.io/llms.txt) · [API overview](https://stylome.io/api/docs)

# API authentication

The [documentation](https://stylome.io/api/docs), [OpenAPI schema](https://stylome.io/api/openapi.json), model catalog, and status endpoint are public. Scoring and account reads require `Authorization: Bearer <credential>`. A missing, invalid, expired, or revoked credential cannot authorize a scoring call.

## Create and protect a developer key

Sign in to your [Stylome account](https://stylome.io/account), add prepaid API credit, and commission a developer API key. Save the secret when it is issued. Keep it on your server or in a secret manager; do not embed it in browser code, commit it to a repository, or include it in a URL.

Set `STYLOME_API_KEY` in your environment using your normal secret-management process. This command checks the credential without scoring text:

```bash
curl --fail-with-body https://stylome.io/api/v1/key \
  --header "Authorization: Bearer $STYLOME_API_KEY"
```

The response has `object: "api_key"`, `public_id`, `project_id`, `scopes`, `retention_mode`, nullable `expires_at`, and `rate_limit_exempt`. The public ID identifies a key without exposing its secret. Use it, rather than the secret, in usage filters.

## Scopes

| Scope | Permission |
| --- | --- |
| `score:create` | Call `POST /api/v1/score` |
| `account:read` | Read quota, retention, idempotency support, and prepaid balance at `GET /api/v1/limits` |
| `usage:read` | Read request-ledger reports at `GET /api/v1/usage` |

`GET /api/v1/key` accepts an authenticated key without an additional read scope. Existing keys retain their original permissions. Commission a replacement if an integration needs additional scopes. Missing credentials produce `401`; insufficient permission produces an authorization error. Check the structured error code and `WWW-Authenticate` header.

The API also accepts approved OAuth access tokens in the Bearer header. An OAuth integration must use its approved authorization flow and granted scopes. A website login cookie is not a substitute for a developer API credential. Agent registration retains its human-session approval boundary; public documentation does not bypass it.

Approved OAuth access tokens use `zero_content` retention and expire in one hour. There is no refresh-token grant. Access also ends when the originating browser session signs out or expires, the owner resets their password, or the grant or client is revoked. Stop paid calls when access ends and obtain a new approved authorization. Do not blindly retry or assume that a website session can refresh a token. See the [authentication flow reference](https://stylome.io/auth.md) for approval and revocation details.

## Choose retention when issuing the key

The retention mode is fixed for a key. Choose `standard` or `zero_content` when commissioning it. An omitted request option cannot silently change that policy. Both public models support zero customer-content retention.

For `zero_content`, do not send `Idempotency-Key`: the API returns `400` because replay needs stored request-derived data. The caller still receives the score and content hash, but Stylome does not retain them. Read the complete [billing and privacy reference](https://stylome.io/api/docs/billing-and-privacy) before choosing a mode.

## Credential failures

Never retry an invalid credential in a loop. Check that the key is active, not expired or revoked, and has the required scope. Rotate a disclosed secret through the account controls and replace it in your integration. Retain `X-Request-ID` for support; never log the Authorization header.

Next: [send a scoring request](https://stylome.io/api/docs/scoring), or inspect [limits and usage](https://stylome.io/api/docs/operations).