API authentication

The documentation, OpenAPI schema, 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, 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:

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

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 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 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, or inspect limits and usage.