# OAuth 2.1 social API authentication
URL: https://skedcast.com/developers/authentication

SkedCast supports OAuth 2.1 social API authentication for third-party apps and AI agents, plus a simple Bearer API key for your own scripts. Every request authenticates with one secret in the Authorization header — use an API key for your own code, or OAuth 2.1 when a third-party app or AI agent acts on a user's behalf.

## API keys
An API key is a long-lived credential you create in Settings → Developer (Owner/Manager). It carries a curated set of scopes; its effective power is always your scopes ∩ your role, so a key can never exceed what the owning member can do.
Send it as a Bearer token on every request:

## Example
```http
GET /v1/agency HTTP/1.1
Host: api.skedcast.com
Authorization: Bearer sked_live_AB12…
```

## Keep keys server-side
An API key grants real access to your workspace. Never embed it in a browser, mobile app, or public repo. Only its SHA-256 hash is stored on our side, so the raw value is shown once at creation — if it leaks, rotate it (Settings → Developer → Rotate), which swaps the secret in place and kills the old one immediately.

## OAuth 2.1 social API authentication (for third-party apps)
When an app or AI agent acts on behalf of a SkedCast user, use the OAuth 2.1 Authorization Code flow with PKCE (S256 required). Clients register dynamically (RFC 7591) — no manual app setup — and discover every endpoint from the metadata documents below.
Access tokens are audience-bound (RFC 8707): request `resource=https://api.skedcast.com/v1` on /oauth/authorize to call the REST API — omitting it at the authorize step yields an MCP-only token. See the OAuth guide for the full flow.

## OAuth endpoints
Method | Path | Purpose
GET | `/.well-known/oauth-authorization-server` | AS metadata (RFC 8414)
GET | `/.well-known/jwks.json` | Public keys for token verification
POST | `/oauth/register` | Dynamic client registration (RFC 7591)
GET/PUT/DELETE | `/oauth/register/:id` | Manage a registration (RFC 7592)
GET | `/oauth/authorize` | Authorization endpoint (PKCE)
POST | `/oauth/token` | Exchange code / refresh for an access token
POST | `/oauth/revoke` | Revoke a refresh token + its rotation family (RFC 7009) — always 200

## The flow, end to end
- Discover the AS metadata from the well-known document.
- Register your client (DCR) to get a client_id.
- Redirect the user to /oauth/authorize with a PKCE code_challenge + your scopes.
- The user signs in and consents; you receive an authorization code.
- Exchange the code at /oauth/token (with the code_verifier) for an access_token + refresh_token.
- Call the API with Authorization: Bearer <access_token> — the token must have been issued for the REST API resource (`resource=https://api.skedcast.com/v1`); refresh when it expires.

## Refresh-token rotation
Refresh tokens rotate on every use and are reuse-detected: presenting a consumed refresh token revokes the whole token family (OAuth 2.1 §4.3.1). Always store and use the newest refresh token returned.

## FAQ
**Q: Should I use an API key or OAuth?**
A: Use an API key for your own server-side scripts and integrations. Use OAuth when you're building an app that other SkedCast users authorize to access their own workspaces.

**Q: How long do access tokens last?**
A: OAuth access tokens are valid for 15 minutes; use the refresh token (valid 30 days, rotating on every use) to obtain a new one, or revoke it at /oauth/revoke. API keys are long-lived with a mandatory expiry (up to a year) and can be revoked or rotated at any time.