Authentication

Every request carries one header:

curl https://api.mageran.ai/api/v1/balance \
  --header 'x-mager-api-key: YOUR_API_KEY'

There is no OAuth flow and no token to refresh. The key is the credential.

Getting a key

1. Request a developer account from the Mager dashboard. It starts as PENDING.
2. Wait for approval. Keys cannot be created until the account is APPROVED.
3. Create a key. The plaintext value is returned once, at creation.

Mager stores only a hash of the key. If you lose it, rotate the key and update your application — there is no way to recover the original.

Scopes

A key carries a set of scopes. A request to an endpoint your key does not cover fails with 403, regardless of whether the account is otherwise healthy.

New keys are created with all five unless you narrow them. Narrow them when you can: a key that only reads templates cannot spend your balance.

Keys issued before CLIPPING existed keep the scopes they were created with, so an older key cannot reach the Clipping Engine. Create a new key to use it.

IP allowlists

A key can be restricted to a list of source IPs. When the list is non-empty, a request from any other address is rejected with 403, even if the key is otherwise valid.

Mager reads the client address from x-forwarded-for when present, falling back to the socket address. If your traffic egresses through a NAT gateway with a stable address, this is worth turning on.

Rotation and revocation

Rotate replaces the secret on an existing key and returns the new plaintext value. The previous secret stops working immediately, so deploy the new one before rotating, or accept a gap.

Revoke deactivates the key. Requests using it fail from the next call onward.

Both actions happen in the dashboard.

Expiry

A key can be given an expiry date. After it passes, the key is rejected the same way a revoked key is. Keys created without one do not expire.

What failure looks like

The response body follows the standard error envelope.