sparka home

Authentication

Sparka has three kinds of credentials. The prefix of each token tells Sparka what it is. Sending the wrong kind to an endpoint returns wrong_credential_type, naming the kinds that endpoint accepts.

Secret keys

A secret key (spk_live_…) acts for your whole account. Send it in the Authorization header:

curl https://sparka.io/v1/account -H "Authorization: Bearer spk_live_..."
  • Create and revoke keys on your account page, up to 10 at a time. The full key is shown once; afterwards only its last 4 characters are.
  • Never put a secret key in a web page, a deck or a public repository. A request that carries a secret key and a browser Origin header is refused with secret_key_in_browser. Decks use the presentation ID instead (below).
  • Rotate a key by creating a new one, switching your code over, then revoking the old one. Revocation takes effect within 60 seconds.
  • On the MCP endpoint a key may also be sent as X-API-Key: spk_live_….

MCP sign-in (OAuth)

Assistants that support MCP sign-in open a Sparka window, you sign in with Google, Amazon or your email and approve the app, and the assistant gets its own token. You can disconnect an app on your account page at any time. For client authors:

Item Value
Resource https://sparka.io/mcp
Protected resource metadata https://sparka.io/.well-known/oauth-protected-resource/mcp (also at /.well-known/oauth-protected-resource)
Authorization server metadata https://sparka.io/.well-known/oauth-authorization-server
Client registration Client ID metadata documents (an https:// URL as client_id), or dynamic registration at POST /oauth/register
Client type Public clients only (token_endpoint_auth_method: none)
PKCE Required, S256 only
Scope sparka (offline_access is accepted and ignored)
Redirect URIs Exact match; http://127.0.0.1, http://[::1] and http://localhost match on any port
Access token oat_…, 1 hour
Refresh token ort_…, 30 days, rotated on every use

Access tokens work only on /mcp. On any other endpoint they return wrong_credential_type. An unauthenticated tools/call of a tool that needs an account returns 401 with a WWW-Authenticate header pointing at the protected resource metadata, which starts the sign-in.

Capability IDs and tokens

Decks run in browsers, so they never hold a secret key. They use capabilities instead: whoever has the value can do one narrow thing.

Value What it allows
Presentation ID pr_… Read the public view of the presentation (no correct answers) and start or resume its live session. It goes in the URL path; no header.
Control token ctl_… Drive one live session: move between questions, reveal, end. Returned when a session starts; it stays the same for the session's lifetime. Sent as Authorization: Bearer ctl_…, or in the first WebSocket message.
Participant token ptk_… One participant's seat in one session, so a phone can rejoin after losing its connection.

Anyone with a presentation ID can start a session on your plan, so share it only in decks you would show anyway. Sessions end after two hours without activity, and the number of new sessions per hour is limited (see Limits).