Spark Account OAuth API

Overview

Spark Account implements the OAuth 2.0 authorization code grant. The flow is three steps:

1. 1 Redirect the user to the authorization endpoint.
2. 2 Exchange the returned code for an access token.
3. 3 Call the userinfo endpoint with that token to read the user's profile.

Endpoints

Scopes

Request only what you need. Space-separate multiple scopes in the scope parameter.

1. Authorization request

Send the user's browser to the authorization endpoint. After they approve, they're redirected back to your redirect_uri with a code (and your state).

https://sparkden.org/api/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=profile email
  &state=RANDOM_STRING

2. Token exchange

Exchange the authorization code for an access token from your server. Credentials can be sent in the body (shown) or as HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)).

curl -X POST https://sparkden.org/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=THE_CODE_FROM_REDIRECT" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGci...",
  "scope": "profile email",
  "id_token": "eyJhbGci..."   // OIDC identity token (RS256, verify via JWKS)
}

3. User info

Use the access token to fetch the user's profile. Fields returned depend on the granted scopes — email and email_verified are only included when the email scope was granted.

curl https://sparkden.org/api/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response

{
  "sub": "a1b2c3d4-...",
  "uid": "a1b2c3d4-...",
  "username": "janedoe",
  "email": "jane@example.com",      // only with email scope
  "email_verified": true,            // only with email scope
  "roles": ["ADULT", "VERIFIED", "SPARKCLOUD"],
  "role": "VERIFIED",
  "verified": true,
  "id_verified": true,
  "sparkcloud_access": true,
  "chat_member": true,
  "chat_admin": false,
  "name": "Jane Doe",
  "avatar_url": "https://...",
  "created_at": "2026-01-12T...",
  "sparks_balance": 1250              // only with sparks scope
}

Student verification

Spark Account can verify a user's real-world identity. Your app can both read a user's verification status and require it before authorization.

Reading verification status

The userinfo response includes the user's verification state — check whichever you prefer:

• verified / id_verified — true once the user has passed identity verification.
• roles — the full set, e.g. STUDENT/ADULT (account type), VERIFIED, SPARKCLOUD, CHAT_MEMBER, CHAT_ADMIN, ADMIN. Gate access on the role you need (e.g. SPARKCLOUD).
• sparkcloud_access — convenience boolean, true when roles includes SPARKCLOUD (or ADMIN).

Requiring verification

Sparks

Sparks are the program-wide currency members earn for building and learning, and spend in the Sparks shop. With the sparks scope your app can read a member's balance and the ledger behind it — useful for showing what they've earned through your app, or gating a feature on a balance.

Balance only

If all you need is the number, the userinfo response carries sparks_balance whenever the sparks scope is granted — no second request.

Balance and history

The Sparks endpoint returns the balance plus the ledger entries behind it, newest first.

curl "https://sparkden.org/api/oauth/sparks?limit=3" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response

{
  "sub": "a1b2c3d4-...",
  "balance": 1250,
  "transactions": [
    {
      "id": "9f8e7d6c-...",
      "delta": -500,
      "balance_after": 1250,
      "reason": "SparkCloud credit voucher",
      "kind": "SPEND",
      "actor_name": null,
      "created_at": "2026-08-14T18:02:11.442Z"
    },
    {
      "id": "3c2b1a09-...",
      "delta": 250,
      "balance_after": 1750,
      "reason": "Shipped your first site",
      "kind": "GRANT",
      "actor_name": "avery",
      "created_at": "2026-08-02T14:20:05.118Z"
    }
  ],
  "next_cursor": "3c2b1a09-..."
}

Paging the ledger

Pagination is cursor-based. Read a page, then pass its next_cursor back as ?cursor= to get the one after it; keep going until next_cursor is null. Ledger entries are immutable once written, so a cursor stays valid — a page you fetch tomorrow lines up with the one you fetched today.

Notes

• Whole numbers. Balances and deltas are always integers. Never render a Spark as a decimal or convert it to a currency — Sparks are priced in Sparks.
• balance_after is authoritative. Each entry records the balance immediately after it, so you can show history without summing deltas yourself.
• The economy can be closed. When it is, this endpoint returns economy_disabled (HTTP 403) and sparks_balance is absent from userinfo — absent, not 0. Treat it as "no balance to show", not "a balance of zero".
• Rate limit. 120 requests per minute, matching userinfo.

Sending email

Verified apps can send emails to their users through Spark Account — no SMTP setup, no separate email provider. Every message is wrapped in a clean, Spark-styled template that carries your app's branding and a clear "sent from [your app] via Spark Account" disclosure, so users always know who's emailing them and why.

Branding

Set a logo URL and brand color on your app under Account → OAuth Apps. The logo appears at the top of every email (and on the consent screen); the brand color is used for the accent bar and call-to-action button. No branding set? Emails fall back to a neutral monogram and Spark orange.

Request

Authenticate with the user's access token. The email is always delivered to the token holder's account email address — you never need (or get) the address itself.

curl -X POST https://sparkden.org/api/oauth/email \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Your weekly project report",
    "title": "Your projects this week",
    "body": "Hi! You shipped 4 new builds this week.\n\nKeep it up — your streak is now 3 weeks.",
    "cta_url": "https://yourapp.com/dashboard",
    "cta_text": "View dashboard"
  }'

Response

{ "ok": true }

Content rules & limits

• Plain text only. Any HTML in subject, title, or body is escaped, not rendered. Blank lines become paragraph breaks.
• One link. The optional cta_url button is the only clickable link — it must be a valid http(s) URL.
• Rate limits. Per user, each app may send 5 emails/hour and 20 emails/day. Exceeding either returns rate_limited (HTTP 429).
• Revocable. Users can stop your emails at any time by revoking your app's access from their account.

Refresh tokens

Access tokens expire after 1 hour. Use the refresh token to get a new pair without sending the user through the flow again. Refresh tokens are single-use — store the new one from each response.

curl -X POST https://sparkden.org/api/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Account events

The events endpoint lets a registered app notify Spark Account of account lifecycle changes — for example, when your app suspends or deletes a user. Spark Account applies the change locally and re-fans it to every other connected app.

Request

curl -X POST https://sparkden.org/api/oauth/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
  -d '{
    "type": "user.suspended",
    "sub": "a1b2c3d4-...",
    "reason": "Violated community guidelines"
  }'

Event types

Response

{ "ok": true }

Outbound webhooks

Register an Event Webhook URL on your OAuth app (via an admin) and Spark Account will POST account lifecycle events to it whenever a user is suspended, unsuspended, or deleted — whether triggered by an admin action or by another connected app.

Payload

// POST to your registered eventWebhookUrl
// Headers:
//   Content-Type: application/json
//   X-Spark-Event: user.suspended
//   X-Spark-Signature: sha256=abc123...

{
  "type": "user.suspended",
  "sub": "a1b2c3d4-...",
  "reason": "Violated community guidelines",
  "ts": 1748908800000
}

Verifying signatures

Every webhook request includes an X-Spark-Signature header of the form sha256=<hex>. Compute an HMAC-SHA256 of the raw request body using your client secret as the key and compare using a constant-time function. Reject requests where the signature doesn't match.

import crypto from 'crypto';

function verifySparkSignature(rawBody, signature, clientSecret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', clientSecret)
          .update(rawBody)
          .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your webhook handler:
app.post('/webhook', express.text({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-spark-signature'];
  if (!verifySparkSignature(req.body, sig, CLIENT_SECRET)) {
    return res.status(401).json({ error: 'invalid_signature' });
  }
  const event = JSON.parse(req.body);
  // handle event.type: 'user.suspended' | 'user.unsuspended' | 'user.deleted'
  res.json({ ok: true });
});

Errors

Token and userinfo errors are returned as JSON with an error field. Authorization errors are appended to your redirect_uri as query parameters.