# StemConsole auth.md

How AI agents and scripts get credentials for StemConsole, and how to use them.

## Who this is for

Agents, scripts and apps that act for a person who has a StemConsole account: splitting their songs into stems, reading results and download links, and managing their library and setlists. Everything runs on that person's own plan and allowance. StemConsole does not issue credentials to agents that act for no one.

## What needs no credentials

- `GET https://stemconsole.ai/llms.txt` and any page with `Accept: text/markdown`
- The MCP tools `get_capabilities` and `get_task_url` at `https://stemconsole.ai/mcp`
- `GET https://stemconsole.ai/api/v1/health` and `GET https://stemconsole.ai/api/v1/openapi.json`

## Getting a credential: OAuth (apps acting for a person)

StemConsole is an OAuth 2.1 authorization server for its own API, MCP server and A2A agent.

- Authorization server metadata: https://stemconsole.ai/.well-known/oauth-authorization-server
- Protected resource metadata (RFC 9728): https://stemconsole.ai/.well-known/oauth-protected-resource, and per resource at `/.well-known/oauth-protected-resource/mcp/account`, `/mcp`, `/api/v1` and `/a2a`
- Dynamic client registration (RFC 7591): `POST https://stemconsole.ai/oauth/register` with `{"client_name", "redirect_uris"}`. Public clients only (`token_endpoint_auth_method` `none`). Redirect URIs must be https, http on localhost, or the app's own scheme.
- Authorization: `https://stemconsole.ai/oauth/authorize` with `response_type=code` and PKCE (`code_challenge_method=S256`, required). The person signs in to StemConsole and approves the app. The one scope is `account`. `resource` (RFC 8707) may name any StemConsole resource above.
- Token: `POST https://stemconsole.ai/oauth/token` with `authorization_code` or `refresh_token`. Access tokens (`sc_at_...`) last an hour; refresh tokens (`sc_rt_...`) rotate on every use.
- Revocation (RFC 7009): `POST https://stemconsole.ai/oauth/revoke`. The person can also disconnect the app on https://stemconsole.ai/developers/.

MCP clients can simply connect to `https://stemconsole.ai/mcp/account`: it answers `401` with a `WWW-Authenticate` challenge that points at the metadata above, which starts this flow.

## Getting a credential: API key (scripts)

1. The person signs in at https://stemconsole.ai/developers/ (Google, or an email link from the homepage). A free account works.
2. They create an API key there and give it to the agent. Keys look like `sc_live_` followed by 43 characters.
3. The key is shown once. StemConsole stores only its SHA-256 hash.

Provisioning is done by the person, in the browser. There is no endpoint that issues a key to an agent, and neither a key nor an OAuth token can create or revoke keys.

## Using it

Send the key or the OAuth access token as a bearer token on every request:

```
Authorization: Bearer sc_live_...
```

- REST API: `https://stemconsole.ai/api/v1` (OpenAPI: https://stemconsole.ai/api/v1/openapi.json)
- MCP server: `https://stemconsole.ai/mcp` (Streamable HTTP; tools that need an account ask for the header) or `https://stemconsole.ai/mcp/account` (always needs it)
- A2A agent: `https://stemconsole.ai/a2a` (JSON-RPC, A2A 1.0); agent card at https://stemconsole.ai/.well-known/agent-card.json

A missing, unknown or revoked key gets `401` with a `WWW-Authenticate: Bearer` challenge and a JSON body such as `{"error": "invalid_api_key", "message": "..."}`.

## What a credential can do

A key or an OAuth token acts as the account that made or approved it, through the API only: split songs (one at a time or up to 10 per batch), read results and download links, list, rename and delete songs, and create and edit setlists (Pro). It spends the account's allowance exactly as the website does. Each account can submit 10 songs an hour, with 2 splitting at once. It cannot buy plans or credits, change billing, or manage keys.

## Revoking

The person revokes a key or disconnects an app at https://stemconsole.ai/developers/. It stops working within a minute.

## Contact

dan@stemconsole.ai