# Auth.md for SuperPowers AI agents

SuperPowers AI supports developer API keys and OAuth 2.0 Authorization Code with PKCE. OAuth clients can request resource-bound, least-privilege access to the OpenAI-compatible Super API or the hosted Super MCP server. A user must sign in to Super before OAuth access is granted. The Android phone-farm MCP tier is free; credits are required only when a tool invokes a premium model, Mac, iPhone, Meta Display, computer-use cache, or other paid service.

## Agent audience

This document is for AI agents and developer tools that need credentials for:

- Canonical Super API resource: `https://app.getsupers.com/v1`
- Root discovery resource aliases: `https://getsupers.com` and `https://app.getsupers.com`
- Hosted Super MCP resource: `https://app.getsupers.com/mcp`
- OpenAI free Android MCP resource: `https://app.getsupers.com/mcp/android`

Tokens are audience-bound. Never send a Super API key or Super API OAuth token to MCP, and never send an MCP OAuth token to a Super API endpoint.

## Machine-readable discovery

- Super API Protected Resource Metadata: `https://getsupers.com/.well-known/oauth-protected-resource`
- Canonical Super API Protected Resource Metadata: `https://app.getsupers.com/.well-known/oauth-protected-resource/v1`
- MCP Protected Resource Metadata: `https://app.getsupers.com/.well-known/oauth-protected-resource/mcp`
- OpenAI Android MCP Protected Resource Metadata: `https://app.getsupers.com/.well-known/oauth-protected-resource/mcp/android`
- OAuth Authorization Server Metadata: `https://getsupers.com/.well-known/oauth-authorization-server`
- Canonical OAuth issuer: `https://app.getsupers.com`
- JSON Web Key Set: `https://app.getsupers.com/.well-known/jwks.json`
- Dynamic Client Registration: `https://app.getsupers.com/oauth/register`
- Token revocation: `https://app.getsupers.com/oauth/revoke`

The authorization server issues opaque bearer access tokens, so the published JWK Set is intentionally empty. Resource servers validate tokens against the issuer's token store.

## Agent registration

The published `agent_auth` registration method is anonymous public-client registration. It registers an OAuth client without a client secret, then uses the authorization endpoint as the claim step where the user signs in and approves access. Anonymous Super account creation and unattended user impersonation are not supported.

Register a public client with HTTPS or localhost loopback redirect URIs:

```http
POST /oauth/register HTTP/1.1
Host: app.getsupers.com
Content-Type: application/json

{
  "client_name": "AGENT_CLIENT_NAME",
  "redirect_uris": ["https://AGENT_CLIENT_HOST/oauth/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

The response includes a `client_id`. Store it with the registered redirect URI; no client secret is issued. The resulting credential type is an OAuth `access_token`. Generate a fresh PKCE verifier and `S256` challenge for every authorization attempt.

## Authorize the Super API

Open the authorization endpoint with the registered `client_id`, exact `redirect_uri`, `response_type=code`, PKCE challenge, requested `scope`, state, and resource indicator:

```text
https://app.getsupers.com/oauth/authorize
  ?client_id=OAUTH_CLIENT_ID
  &redirect_uri=URL_ENCODED_REGISTERED_REDIRECT_URI
  &response_type=code
  &code_challenge=PKCE_S256_CHALLENGE
  &code_challenge_method=S256
  &scope=api%3Amodels%20api%3Achat
  &resource=https%3A%2F%2Fapp.getsupers.com%2Fv1
  &state=UNGUESSABLE_STATE
```

The user signs in with the phone or email attached to the Super account, adds credits when necessary, reviews the named scopes, and approves access. Verify the returned `state` and issuer, then exchange the single-use code at `/oauth/token` with the original PKCE verifier and the exact resource value. Agents that begin at either root Protected Resource Metadata document may use its exact root resource identifier; those resource-bound tokens are accepted by the same Super API operations as the canonical `/v1` resource.

### Super API scopes

- `api:models` lists currently available models and account credit metadata.
- `api:chat` creates OpenAI-compatible chat completions.
- `api:completions` creates legacy text completions.
- `commerce:subscribe` purchases or renews the owner-scoped $199 monthly Super Powers AI Pro plan through UCP, MPP, or x402.

Request only the scopes required by the agent. A valid token without an operation's scope receives HTTP 403 and a `WWW-Authenticate` challenge naming the required scope.

## Authorize hosted MCP

Use the same registration and PKCE process with:

- Resource: `https://app.getsupers.com/mcp`
- Free scope: `mcp:android` for Android APK setup, owner-scoped device listing, and Android phone-farm commands
- Additional scopes: `mcp:chat`, `mcp:projects`, and `mcp:devices`
- MCP endpoint: `https://app.getsupers.com/mcp`
- Server Card: `https://getsupers.com/.well-known/mcp/server-card.json`

Every project, chat, and WebRTC device room is derived from the authenticated token owner. A client cannot select another owner by sending an account identifier.

### Authorize the OpenAI free Android MCP

For the separate OpenAI listing, use only:

- Resource: `https://app.getsupers.com/mcp/android`
- Scope: `mcp:android`
- MCP endpoint: `https://app.getsupers.com/mcp/android`
- Server Card: `https://getsupers.com/.well-known/mcp/android/server-card.json`

This resource requires Super login, exposes only setup, single-device listing, and Android command execution, and returns at most one Android APK device owned by the signed-in account. Its token is not accepted by the general hosted MCP or Super API.

## Present and revoke OAuth credentials

Present the access token only to its declared resource:

```http
Authorization: Bearer mcp_access_...
```

Revoke an OAuth token using RFC 7009 form encoding. Revocation returns HTTP 200 for valid and already-invalid tokens:

```http
POST /oauth/revoke HTTP/1.1
Host: app.getsupers.com
Content-Type: application/x-www-form-urlencoded

token=URL_ENCODED_ACCESS_TOKEN&token_type_hint=access_token
```

## Dashboard API keys

Users can alternatively create and revoke a bearer API key at `https://app.getsupers.com/developer/api-dashboard`. Send the complete `sk-supers-...` value to Super API endpoints as:

```http
Authorization: Bearer sk-supers-...
```

API key creation requires an authenticated human Super account session. Keep keys server-side and never expose credentials in public HTML, browser bundles, source control, logs, screenshots, URLs, query strings, or agent-visible output.

## Recovery

If a bearer credential returns HTTP 401, discard it and restart discovery. If it returns `insufficient_scope`, repeat authorization for the same resource with the required scope. OAuth approval itself is free. A premium tool may return an `insufficient_credits` result with an owner-safe upgrade URL; the user completes payment in Super and can then retry the tool with the same authorized connection.

## Discovery resources

- [SuperPowers AI Developer Portal](https://getsupers.com/developers/)
- [OpenAPI 3.1 specification](https://getsupers.com/openapi.json)
- [RFC 9727 API catalog](https://getsupers.com/.well-known/api-catalog)
- [Super API Agent Skill](https://getsupers.com/.well-known/agent-skills/super-api/SKILL.md)
- [Agentic Resource Discovery catalog](https://getsupers.com/.well-known/ai-catalog.json)
- [Super hosted MCP Server Card](https://getsupers.com/.well-known/mcp/server-card.json)
- [Super Android MCP Server Card](https://getsupers.com/.well-known/mcp/android/server-card.json)