# Authenticating with Sprkly

Sprkly supports two credential types:

- **Bearer API keys** — for the REST API, and for MCP clients that use a fixed credential.
- **OAuth 2.1** — for MCP connectors. Dynamic Client Registration (RFC 7591) and Client ID Metadata Documents are both supported, PKCE S256 is required.

## REST API

1. Sign in at https://sprkly.app and open **Settings**.
2. Create an **API key** and copy it (shown once).
3. Send it on every request:

    Authorization: Bearer <YOUR_API_KEY>

Scopes (assigned per key): `post:write`, `post:read`, `post:draft`, `media:write`, `account:read`, `approval:request`.

- API description (OpenAPI): https://sprkly.app/openapi.json
- API catalog: https://sprkly.app/.well-known/api-catalog
- Human docs: https://sprkly.app/docs/api
- Health: https://sprkly.app/api/health

## MCP server (AI agents)

- Endpoint: https://sprkly.app/api/mcp (transport: streamable-http, stateless)
- Server card: https://sprkly.app/.well-known/mcp/server-card.json
- Discovery: https://sprkly.app/.well-known/mcp.json
- Docs: https://sprkly.app/docs/mcp
- Setup per client: https://sprkly.app/integrations

### Option 1 — OAuth 2.1 (recommended)

Add https://sprkly.app/api/mcp as a custom connector and authorize. Discovery chain:

1. An unauthenticated tool call returns `401` with
   `WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://sprkly.app/.well-known/oauth-protected-resource/api/mcp"`
2. That document names the authorization server: https://sprkly.app
3. Authorization server metadata: https://sprkly.app/.well-known/oauth-authorization-server

Scopes: `profile`, `mcp:read`, `mcp:write`. Add `offline_access` for a refresh token.

`initialize` and `tools/list` work without credentials, so a client can list the tools before the user signs in.

### Option 2 — API key

Send the same `sk_live_` key as a bearer token directly to the MCP endpoint. No exchange step:

    Authorization: Bearer <YOUR_API_KEY>

### Tools

- `sprkly_delete_scheduled_post`
- `sprkly_draft_post`
- `sprkly_get_account_summary`
- `sprkly_get_billing_summary`
- `sprkly_get_post_approval_status`
- `sprkly_get_post_status`
- `sprkly_list_connected_social_accounts`
- `sprkly_list_profiles`
- `sprkly_list_scheduled_posts`
- `sprkly_request_post_approval`
- `sprkly_schedule_post`
- `sprkly_update_scheduled_post`
- `sprkly_validate_post_policy`

### Deprecated

`POST https://mcp.sprkly.app/auth` (API key -> short-lived JWT) and `POST https://sprkly.app/api/auth/mcp-token` still work, but no new integration needs them. `https://mcp.sprkly.app/mcp` proxies to the endpoint above.

## Requirements

MCP and REST API access both require an active paid plan.

## Contact

Questions about programmatic access: support@sprkly.app