Get started
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.
BetaUpdated
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.
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?#
- Sign in and open the dashboard.
- Expand Developers and choose the scopes the key needs.
- Pick an expiry: never, 7 days, 30 days, 90 days, or 1 year.
- 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.
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 lists its required scope. The dashboard also offers scopes for other LyricWinter products; they are not needed for Studio.
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 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:readand, 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:readandstudio:writeasAuthorization: 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 is the exception: it allows cross-origin reads so that API tools can load it.