---
name: layer-api-authentication
description: Obtain a credential for the Layer API and make an authenticated call. Use when a request to api.app.layer.ai returns 401 or 403, when choosing between a Personal Access Token and OAuth 2.0, or when deciding which workspace role an integration user needs.
---

# Authenticate against the Layer API

Layer is the AI platform for creative teams in games and entertainment. Its REST API is at
`https://api.app.layer.ai/api`, path-versioned as `/v1` and `/v2`.

## Pick a credential

**Personal Access Token** — for a script, a backend service, or anything without a browser.
Create it yourself in the app under **Settings → Personal Access Tokens**; there is no approval
step, no sales contact, and no REST endpoint that mints, lists, or revokes tokens. The value is
shown once. Send it on every request:

```
Authorization: Bearer pat_...
```

**OAuth 2.0** — for an MCP client or any app acting on behalf of a signed-in user. Authorization
code with PKCE, and dynamic client registration, so no pre-registered client id is needed. The
authorization server is `https://auth.app.layer.ai/`; its RFC 8414 metadata is at
<https://auth.app.layer.ai/.well-known/oauth-authorization-server>. Issued scopes are `openid`,
`profile`, `email`, `offline_access` — there are no Layer API scopes to request.

## Understand what the credential can do

Layer authorizes the **calling user**, not the credential. Access is evaluated against that
user's role in the target workspace (`VIEWER`, `MEMBER`, `ADMIN`, `OWNER`) and, for
project-scoped resources, their project membership. As a rule: `GET` needs `VIEWER`, and anything
that creates, changes, or starts a run needs at least `MEMBER`.

A Personal Access Token inherits **all** of its creating user's permissions — there are no
per-token scopes. To limit an integration, provision a dedicated Layer user and give that user
only the workspace role and project membership it needs.

## Find the workspace id

Almost every path is workspace-scoped. List the workspaces the credential can reach:

```bash
curl -H "Authorization: Bearer $LAYER_TOKEN" \
  https://api.app.layer.ai/api/v2/workspaces
```

## Handle the failures

- **401** — the token is missing, malformed, or expired. On an MCP endpoint the 401 carries
  `WWW-Authenticate: Bearer resource_metadata=…`; follow it to the RFC 9728 protected-resource
  metadata, then to the authorization server.
- **403** — the credential is valid but the user's role is too low for this operation. Raise the
  role or use a different workspace; retrying will not help.
- **429** — a generation rate limit (60 generations/minute per user, of which 30 may be video).
  Wait the `Retry-After` interval, with jitter if several workers share the user. List, get, and
  estimate operations are not rate limited.

Errors are RFC 9457 problem documents (`application/problem+json`) carrying a stable
`error_code`.

## Reference

- Authentication guide: <https://layer.ai/docs/authentication>
- Self-serve access: <https://layer.ai/docs/self-serve-access>
- Unattended onboarding facts, as JSON: <https://layer.ai/api/onboarding.json>
- OpenAPI 3.1 description: <https://layer.ai/openapi.json>