Authenticate API requests

API-key authentication

The recommended header is:

Authorization: Bearer mr_your_key_here

The product runtime also accepts:

x-api-key: mr_your_key_here

Use one authentication form, not both. The OpenAI SDK sends Bearer authentication. Anthropic SDKs normally send x-api-key, but Singular has limited native Anthropic Messages compatibility; see the compatibility guide before using an Anthropic SDK.

Key lifecycle

• Create, list, and revoke programmatic keys in Settings → API keys.
• The full secret is shown only in the create response. The UI stores only a display prefix and the gateway key ID.
• A Settings-created key starts with zero balance. Current account checkout funds the account's default runtime key, not an arbitrary Settings-issued key; there is no self-service per-key funding control in this release.
• read_only maps to the gateway viewer role and read_write maps to the developer role for control-plane permissions. This label is not a spend guard: both roles can authorize inference and consume balance.
• Revocation happens at the gateway before the UI removes the key from the active list.
• A key may still be subject to balance, organization, quota, routing-policy, or provider constraints.

Accountless machine payments

On eligible routes, an enabled deployment may accept a settled x402 or MPP payment instead of a Singular API key. The first request intentionally has no API-key header and receives a 402 Payment Required challenge. A valid payment credential becomes the authorization for that single request.

A generic 402 does not prove that accountless payment is enabled. Clients must inspect the protocol challenge headers and only continue when they can satisfy one of the advertised methods.

Security checklist

• Load keys from a secret manager or server-only environment variable.
• Use separate keys for development, staging, production, and independent services.
• Revoke a key immediately if it appears in a client bundle, log, paste, or repository.
• Do not send legacy x-portkey-* routing or guardrail headers on the public product API; the gateway rejects that legacy control path.
• Bound retries so an application cannot multiply spend during upstream incidents.