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

# Authentication

> Authenticate API requests with a Melius API key and the x-team-id header.

Every request authenticates with an API key passed as a bearer token, plus a header naming the team to act on.

```bash theme={null}
Authorization: Bearer mel_...
x-team-id: <your team id>
```

## Create an API key

In the Melius app, go to **Team settings → Integrations** and create a key. Each key:

* Is shown **once** at creation — copy it before closing the dialog.
* Can be given an expiry, or set to never expire.
* Can be revoked at any time from the same page — revocation takes effect immediately.

<Warning>
  Treat an API key like a password. Don't commit it to source control or expose it in client-side code. Set it from an environment variable or a secrets manager.
</Warning>

## Find your team id

`x-team-id` selects which team a request acts on. List your teams — note that `/teams` returns your **memberships**, so the team id is under `.team.id`:

```bash theme={null}
curl -s -H "Authorization: Bearer mel_..." https://api.melius.com/api/v1/teams \
  | jq '.[] | {teamId: .team.id, name: .team.name, plan: .team.plan, role}'
```

If you omit `x-team-id`, requests default to the team the key was created in.

## How keys are scoped

An API key acts **on behalf of the user who created it**. That has three consequences worth understanding:

* **It spans that user's teams.** A key can act on any team its creator is a member of by passing that team's `x-team-id` — not just the team it was created in. It can never reach a team its creator doesn't belong to.
* **It's capped at the creator's role in each team.** Permissions follow the user's role in the team being acted on, exactly like the app — the key never grants more than that role. Owner/admin-only actions (managing members, billing, team settings) require that role **in the acted-on team**; a viewer can only read. Selecting a different team with `x-team-id` never escalates access.
* **It follows the creator's membership.** If the creating user leaves a team, the key loses access to that team.

For a long-lived production integration, create the key from an account that will remain a member of the team — a dedicated service account rather than a personal login.

## Errors

| Status | Meaning                                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------------------- |
| `401`  | Missing, invalid, expired, or revoked API key.                                                             |
| `403`  | The key's user isn't a member of the requested `x-team-id`, or their role there doesn't permit the action. |
| `429`  | Monthly request limit reached — retry after the `Retry-After` header.                                      |
| `400`  | Invalid request — including not enough credits to run a generation.                                        |

## Next steps

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api/quickstart">
    Run your first generation end to end.
  </Card>

  <Card title="API overview" icon="book-open" href="/api/overview">
    The base URL, the async job model, and how generations work.
  </Card>
</Columns>