Device authorization for agents

Formspring supports an RFC 8628-style device authorization flow. Your agent plugin or CLI requests a short code, you approve the connection in the browser, and the client receives a scoped API token automatically.

When to use it

Cursor / Claude Code plugins - run /formspring:login or scripts/device-auth.sh (see the agent plugin repo) instead of exporting FORMSPRING_TOKEN by hand.
Any HTTP MCP client - use the same endpoints from a script if you prefer browser approval over pasting bearer tokens.

Manual token minting remains available on MCP setup and API tokens.

Flow

Client POST /mcp/device/session with { "client": "cursor", "abilities": ["forms:read", ...] }.
Response includes user_code, device_code, verification_uri_complete, expires_in, and interval.
User opens verification_uri_complete (or /mcp/device?user_code=XXXX-XXXX), signs in, and approves abilities.
Client polls POST /mcp/device/token with { "device_code": "..." } until status is success and access_token is present.

Poll statuses:

`status`	Meaning
`authorization_pending`	Waiting for browser approval
`success`	Token issued (one-time; includes `config_string` for your client)
`access_denied`	User denied in the browser
`expired_token`	Code expired (default 15 minutes)

Discovery

OAuth metadata for automation:

Protected resource: GET /.well-known/oauth-protected-resource/mcp-server
Authorization server: GET /.well-known/oauth-authorization-server

Plugin CLI

From the formspring-ai repository:

bash

./scripts/device-auth.sh cursor
# or
FORMSPRING_DEVICE_CLIENT=claude-code ./scripts/device-auth.sh

The script prints export FORMSPRING_TOKEN=... when finished. Add that to your shell profile or plugin settings.

Security

Device codes are single-use and stored hashed.
Tokens are scoped to the abilities chosen at session start (or adjusted on the approval page).
Revoke access anytime from MCP setup or API tokens.