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

# Authentication & roles

> API keys, session tokens, the master key, and what Admin/Developer/Member can each do.

## Getting a key

Create an account at [platform.r3al.ai](https://platform.r3al.ai) and verify your email, then mint a key on the **SDK / API keys** page. Live keys use the `r3l_live_` prefix.

## Two ways to authenticate

Every `/v1/*` request (except `/v1/auth/*`) reads an `Authorization: Bearer <token>` header. The token can be either of:

<Steps>
  <Step title="A standalone API key">
    Minted via `POST /v1/keys` or the SDK page (prefix `r3l_test_` or `r3l_live_` depending on `env`). Meant for the SDK, scripts, CI, or integrations. This is the credential the Python SDK uses.
  </Step>

  <Step title="A session token">
    Minted by `POST /v1/auth/login` or `/register` (prefix `r3l_sess_`, 30-day expiry). This is what the dashboard uses once you're signed in; it doubles as an API credential.
  </Step>
</Steps>

```bash theme={null}
curl https://platform.r3al.ai/v1/jobs \
  -H "Authorization: Bearer r3l_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

<Warning>
  The key secret is shown **once**, at mint time. Store it securely; if you lose it, revoke it and mint a new one.
</Warning>

## Roles: Admin, Developer, Member

Real platform accounts (`POST /v1/auth/register`) each have exactly one role, enforced server-side on every mutating endpoint:

| Role          | Can do                                                                                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin**     | Everything: run jobs, manage API keys, alert rules, deployments, invite teammates, and change anyone's role (see [Team & roles](/api/team)).                     |
| **Developer** | Full operational access -- run jobs, manage their own API keys, create/delete alert rules, start/stop deployments. Cannot manage invites, other users, or roles. |
| **Member**    | Read-only everywhere. Can list jobs, models, logs, alerts, and deployments, but every create/update/delete call returns `403`.                                   |

<Note>
  Role checks apply when the caller authenticated with a **session token** (a logged-in account). A standalone API key bypasses role checks: role tiering is an account concept layered on top of the API, so the SDK and scripts using a plain key keep unrestricted access.
</Note>

The first account on a team becomes **Admin** automatically. Every self-registration after that defaults to **Member**; an Admin invites someone as Developer or Admin explicitly (`POST /v1/auth/invites` with a `role` field).

### Changing a role

```bash theme={null}
curl -X PATCH https://platform.r3al.ai/v1/auth/users/u_abc123/role \
  -H "Authorization: Bearer <admin session token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "developer"}'
```

Admin-only. Refuses to demote the platform's last remaining Admin (`409 Conflict`) so nobody can lock out all role management by accident.