# Authentication

Every request to `https://viraloop.io/api/v1` is authenticated with an API key. Keys are created in the dashboard at https://viraloop.io/settings/developers and look like `vl_live_...`.

## Sending the key

Two headers are accepted; use whichever fits your HTTP client:

```bash
curl -s https://viraloop.io/api/v1/me \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"
```

```bash
curl -s https://viraloop.io/api/v1/me \
  -H "X-API-Key: $VIRALOOP_API_KEY"
```

Keys are accepted in headers only. Never put a key in a URL or query string; URLs end up in logs.

A missing or invalid key returns `401` with error type `unauthorized`.

## Scopes

Each key carries a set of scopes chosen at creation. Calling an endpoint the key is not scoped for returns `403` with error type `forbidden_scope`.

- `credits:read`: read the credit balance and ledger (GET /credits)
- `workspaces:read`: list and read workspaces (GET /workspaces, GET /workspaces/{id})
- `workspaces:write`: create workspaces (POST /workspaces)
- `accounts:read`: list connected social accounts (GET /accounts)
- `generations:read`: list and read content suggestions (GET /generations, GET /generations/{id})
- `generations:write`: generate content suggestions (POST /generations)
- `posts:read`: list and read posts and the calendar (GET /posts, GET /posts/{id}, GET /calendar)
- `posts:write`: create and cancel posts (POST /posts, DELETE /posts/{id})

`GET /me` works with any valid key regardless of scopes; use it to check which scopes a key has (`data.auth.scopes`).

## Managing keys

Everything happens at https://viraloop.io/settings/developers:

- Create a key with a name and the scopes it needs
- The full key is shown once, at creation; only a prefix (like `vl_live_a1b2c3d4`) is visible afterwards
- Revoke a key at any time; revoked keys stop working immediately

## Security notes

- Store keys in environment variables or a secret manager, never in source control
- Give each integration its own key with the minimum scopes it needs, so one leak has a small blast radius and revocation does not break everything else
- If a key leaks, revoke it in the dashboard and create a new one
- Keys act on behalf of your team; treat them like passwords