# Agent authentication on GrooveSheet

How an agent gets access to GrooveSheet's API and MCP server, and exactly
which credentials exist. This file lives at `/auth.md`, the discovery path
from the WorkOS auth.md spec (https://github.com/workos/auth.md). GrooveSheet
uses standard OAuth 2.1 rather than that spec's agentic-registration
machinery; this file says what is implemented and what is not.

Last checked against the service on 6 November 2026 (authorization server moved to api.groovesheet.net, verified-email registration and the sandbox added, the same day).

## Discover

- The public MCP server needs no credential at all:
  `https://api.groovesheet.net/mcp/public` (Streamable HTTP). It searches the
  song library and returns score, PDF and Guitar Pro links.
- The full MCP server, `https://api.groovesheet.net/mcp`, and the REST API
  under `https://api.groovesheet.net/` are OAuth-protected. A request without
  a token gets `401` with
  `WWW-Authenticate: Bearer resource_metadata="https://api.groovesheet.net/.well-known/oauth-protected-resource/mcp"`.
- Protected-resource metadata (RFC 9728):
  `https://api.groovesheet.net/.well-known/oauth-protected-resource`, which
  names the authorization server.
- Authorization-server metadata (RFC 8414):
  `https://api.groovesheet.net/.well-known/oauth-authorization-server`
  (also at `/.well-known/openid-configuration`). The issuer is
  `https://api.groovesheet.net`. It lists every endpoint, all on that host:
  `authorization_endpoint` `/oauth/authorize`, `token_endpoint` `/oauth/token`,
  `registration_endpoint` `/oauth/register`, `userinfo_endpoint`
  `/oauth/userinfo` and `jwks_uri` `/oauth/jwks`, plus
  `code_challenge_methods_supported` `["S256"]` and the scopes `openid`,
  `email`, `profile` and `offline_access`. The endpoints are a thin front over
  Supabase Auth, which runs sign-in for groovesheet.net and issues the tokens.
- The metadata carries the WorkOS `agent_auth` block: `skill` (this file),
  `identity_endpoint` `https://api.groovesheet.net/agent/identity`,
  `claim_endpoint` `https://api.groovesheet.net/agent/identity/claim` and
  `identity_types_supported` `["service_auth"]`. There is no `events_endpoint`.

## Pick a method

- **No credential**: the public MCP server, every public page, `/llms.txt`,
  the OpenAPI document at `https://api.groovesheet.net/openapi.json`, and the
  song library pages. Start here; it covers finding and reading sheet music.
- **OAuth 2.1 authorization code with PKCE**: the only credential for the
  full MCP server and the REST API. The token identifies a GrooveSheet user
  account; the agent acts for that user, within that user's plan and minutes.
  MCP clients that support OAuth (Claude, ChatGPT in developer mode, Cursor,
  VS Code, Claude Code) run this flow on their own once given the server URL.
- **Verified-email registration** (`service_auth`): for an agent that knows
  only the user's email and cannot open a browser itself. See Register and
  Claim below; the user still signs in and clicks Allow.
- **API keys**: none. The REST API (https://www.groovesheet.net/developers/docs/api)
  uses the same OAuth tokens. Dynamic client registration is open, so a token
  needs no approval from anyone.
- **Sandbox, no credential**: `https://api.groovesheet.net/sandbox` serves
  every read route and a simulated `POST /sandbox/workflow/{workflow_name}`
  that completes with a demo song's real outputs. Nothing is charged and no
  account is involved, so an integration can be built and tested end to end
  before the first token. The `groovesheet` CLI (`npm i @groovesheet/sdk`)
  takes `--sandbox` for the same thing.

## Register

Two ways, both end with a standard Supabase access token for the user.

**Dynamic client registration** (RFC 7591) is open at the `registration_endpoint`
(`https://api.groovesheet.net/oauth/register`). Register a public client with
your redirect URI and `token_endpoint_auth_method` `none`, or a confidential
client with a secret, then use the authorization-code flow below.

**Verified-email registration** (WorkOS `service_auth`): when the agent only
knows the user's email,

```
POST https://api.groovesheet.net/agent/identity
Content-Type: application/json

{ "type": "service_auth", "login_hint": "user@example.com" }
```

answers `200` with a `claim_token` (keep it), `claim_token_expires` (15 minutes)
and a `claim` block: a 6-digit `user_code`, a `verification_uri`, `expires_in`
(600 seconds) and `interval` (5 seconds). No email is sent; the agent shows
the code and link to the user. Registration is limited to 10 a minute per
address.

Not supported: the WorkOS registration types `anonymous` and
`identity_assertion` (ID-JAG) and the `jwt-bearer` grant; a request for them
answers `400 unsupported_identity_type`. There is no revocation endpoint and
no `events_endpoint`.

## Claim

For authorization-code clients there is no separate claim step: the agent opens
the `authorization_endpoint` in a browser, the user signs in to groovesheet.net
(email, Google or Apple) and clicks **Allow** on
`https://www.groovesheet.net/oauth/consent`, and the server redirects back
with a `code`.

For verified-email registration the user opens the `verification_uri`, types
the `user_code` (five wrong tries invalidate it), signs in to groovesheet.net
and clicks **Allow**. The account they sign in with must have the email given
as `login_hint`; any other account connects nothing. Meanwhile the agent polls:

```
POST https://api.groovesheet.net/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=<claim_token>
```

Answers: `400 authorization_pending` (keep polling at `interval`),
`400 slow_down` (polled too fast), `400 expired_token` (the `user_code` ran out;
`POST /agent/identity/claim` with `{ "claim_token": "...", "email": "..." }`
returns a fresh `claim` block while the 15-minute claim is open),
`400 invalid_grant` (unknown, expired or already collected), or `200` with
`access_token`, `refresh_token`, `expires_in` and `token_type: Bearer`. The
token set can be collected once.

## Exchange

For authorization-code clients: standard exchange at the `token_endpoint`
(`https://api.groovesheet.net/oauth/token`) with the
`code`, the `code_verifier` for your PKCE challenge, and the `client_id`.
The response carries `access_token`, `token_type: Bearer`, `expires_in`, and a
`refresh_token` when `offline_access` was requested. Grant types supported:
`authorization_code`, `refresh_token` and the claim grant above.

## Use the access_token

Send it as a bearer credential:

```
Authorization: Bearer <access_token>
```

on `https://api.groovesheet.net/mcp` (MCP, Streamable HTTP) or on REST calls
under `https://api.groovesheet.net/`. The MCP tools that need it are
`get_account`, `create_upload_link`, `get_upload_status`, `list_my_jobs` and
`get_job`; `search_songs`, `get_song` and `get_download_links` work without
it. No tool spends the user's minutes: transcriptions are started by the user
on groovesheet.net after a free 30-second preview.

## Errors

- `401` with `WWW-Authenticate: Bearer error="invalid_token"` and a JSON body
  `{ "error": "invalid_token", "error_description": "Authentication required" }`:
  no token, an expired token, or a token for another audience. Refresh or
  re-authorize.
- `403`: the token is valid but the account cannot do that (for example a
  job that belongs to another user).
- `404` with a JSON body for an unknown job, upload code or route.
- `429` when rate-limited; the API does not yet send `Retry-After`, so back
  off for a few seconds and retry.
- MCP errors are JSON-RPC errors with `code` and `message`; a tool that
  cannot do what was asked (for example an account with no minutes left)
  answers in text with the next step and the pricing link rather than failing.

## Revocation

A refresh token stops working when the user's session is revoked on the
GrooveSheet side (sign-out from all devices, or on request to support); the
next refresh then fails with `invalid_grant` and the agent must re-authorize
from the Claim step. There is no RFC 7009 `revocation_endpoint` an agent can
call, and no `events_endpoint` for revocation notices. For a compromised
client, email support@groovesheet.net.
