---
title: "Authentication and API key scopes"
description: "Authenticate LyricWinter API requests with scoped lw_ API keys, choose the right scopes, and understand how MCP clients connect through OAuth 2.1."
canonical_url: https://lyricwinter.com/docs/authentication
markdown_url: https://lyricwinter.com/docs/authentication.md
last_updated: 2026-09-30
status: beta
---
# Authentication and API key scopes

> Authenticate LyricWinter API requests with scoped lw_ API keys, choose the right scopes, and understand how MCP clients connect through OAuth 2.1.

The LyricWinter API authenticates every request with a scoped API key sent as a bearer token. MCP clients can use the same kind of key or sign in through OAuth 2.1, which issues a short-lived Studio key on the user's behalf.

```http
Authorization: Bearer lw_...
```

Requests without a valid key return `401 UNAUTHORIZED`. A valid key that lacks the scope an endpoint needs returns `403 FORBIDDEN` with a message such as `API key is missing required scope: studio:write`.

## How do I create a LyricWinter API key?

1. Sign in and open the [dashboard](/dashboard).
2. Expand **Developers** and choose the scopes the key needs.
3. Pick an expiry: never, 7 days, 30 days, 90 days, or 1 year.
4. Create the key and copy it immediately. LyricWinter stores only a hash, so the raw key is shown once.

Keys start with `lw_`. Treat them like passwords: keep them in a secret manager or environment variable, never in source control or client-side code.

You can also manage keys over the API with `GET /api-keys`, `POST /api-keys`, and `DELETE /api-keys/{apiKeyId}`, which need the `api_keys:read` or `api_keys:write` scope. See the [Account API](/docs/api/account).

## Which scopes does a LyricWinter API key need?

Give each key the smallest set of scopes it needs. The scopes used by the endpoints in these docs are:

| Scope | Grants |
| --- | --- |
| `studio:read` | Read Studio projects, sections, documents, speakers, workflows, media, playback, exports, sharing state, and sounds. |
| `studio:write` | Create and change Studio content, start and cancel workflows, create exports, publish links, and upload sounds. Includes paid operations. |
| `account:read` | Read the account profile with `GET /me`. |
| `api_keys:read` | List API keys. |
| `api_keys:write` | Create and revoke API keys. |

Each endpoint in the [API reference](/docs/api) lists its required scope. The dashboard also offers scopes for other LyricWinter products; they are not needed for Studio.

> [!WARNING]
> `studio:write` can start Create Audio workflows, which consume words from the account's balance. Give it only to code you trust to spend that balance.

## How do I revoke a key?

Revoke a key from the dashboard's **Developers** panel or with `DELETE /api-keys/{apiKeyId}`. Revocation takes effect on the next request. Expired keys stop working automatically.

## How do MCP clients authenticate?

The [LyricWinter MCP server](/docs/mcp) accepts two kinds of credentials:

- **OAuth 2.1 (recommended).** The client discovers LyricWinter's authorization server from the MCP server's protected-resource metadata, then runs the authorization code flow with PKCE. The user signs in to LyricWinter and approves `studio:read` and, optionally, `studio:write`. LyricWinter issues a one-hour access token and a rotating 30-day refresh token for that client.
- **A Studio-scoped API key.** For local development or clients without OAuth support, send a key with `studio:read` and `studio:write` as `Authorization: Bearer lw_...`.

OAuth access tokens are bound to the MCP server they were issued for. Each person's connection only reaches their own LyricWinter account. To disconnect an MCP client, revoke its key in the dashboard; that also blocks its refresh token.

| OAuth metadata | URL |
| --- | --- |
| Protected resource | `https://lyricwinter.com/.well-known/oauth-protected-resource/mcp` |
| Authorization server | `https://lyricwinter.com/.well-known/oauth-authorization-server` |
| Authorization endpoint | `https://lyricwinter.com/oauth/authorize` |
| Token endpoint | `https://lyricwinter.com/oauth/token` |
| Dynamic client registration | `https://lyricwinter.com/oauth/register` |

LyricWinter supports public clients (`token_endpoint_auth_method: none`), PKCE with `S256`, the `authorization_code` and `refresh_token` grants, and dynamic client registration with up to five redirect URIs per client.

## Does the API support browser (CORS) requests?

No. Call the LyricWinter API from a server, script, or native app, and keep API keys out of browsers. The public [OpenAPI contract](https://lyricwinter.com/api/v1/openapi.json) is the exception: it allows cross-origin reads so that API tools can load it.