> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Mage API: create a key in Settings → API, send it as a Bearer token, keep it on your servers, and revoke it when needed.

Every request carries an API key in the `Authorization` header. Keys are created in [Settings → API](https://www.mage.space/settings?tab=api). A key belongs to your account, generates as you, and spends your Gems.

## Authorization header

```http theme={null}
Authorization: Bearer mage_sk_...
```

```bash theme={null}
curl --url https://api.mage.space/v1/account \
  --header "Authorization: Bearer $MAGE_API_KEY"
```

## Keys

* A key starts with `mage_sk_` and is shown once, when it is created. Mage stores only a hash of it, so a lost key cannot be recovered: create a new one and revoke the old one.
* An account may hold up to 10 active keys. Name each one for the service or environment that uses it, so revoking one does not take the others down.
* Revoking a key in Settings → API takes effect immediately. Generations already running finish, but the key can no longer submit, read, or cancel requests.
* Settings → API shows when each key was last used.

<Warning>
  Keep keys on your servers. The API sends no CORS headers, so a browser cannot
  call it directly, and a key shipped inside an app can be extracted and used to
  spend your Gems. Store keys in a secrets manager or environment variables,
  never in source control, logs, or URLs, and rotate a key as soon as you
  suspect it leaked.
</Warning>

## Authentication errors

A request without a usable key is refused with `401 unauthorized` and the [error envelope](/api/errors).

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "The API key is invalid or has been revoked."
  }
}
```

A valid key on an account that cannot generate, for example a banned one, is refused with `403 forbidden` when it submits.