OAuth for partner apps

{
  "client_id": "cp_8fK2mQ7xL0aZ4tR9wY1b",
  "owner": "you@example.com",
  "name": "Trade Journal",
  "verified": false,
  "logo_url": null,
  "redirect_uris": ["https://partner.example/callback"],
  "scopes": ["read", "orders"],
  "created_at": "2026-09-28T09:00:00Z",
  "disabled": false,
  "client_secret": "cps_…",
  "note": "Store the client secret now: it is not shown again."
}

User's browser         Your server              Consent screen             API
      |                      |                        |                          |
      | 1. "Connect"         |                        |                          |
      |--------------------->|                        |                          |
      |                      | make verifier, state;  |                          |
      |                      | keep them server-side  |                          |
      | 2. 302 to /oauth/authorize?client_id&redirect_uri&scope&state&code_challenge
      |<---------------------|                        |                          |
      | 3. sign in, review the consent screen, Allow  |                          |
      |---------------------------------------------->| POST /v1/oauth/authorize |
      |                      |                        |------------------------->|
      | 4. 302 to redirect_uri?code=oc_…&state=…      |<-------------------------|
      |<----------------------------------------------|                          |
      |--------------------->| 5. POST /v1/oauth/token (code, code_verifier,     |
      |                      |    client_id + client_secret)                     |
      |                      |-------------------------------------------------->|
      |                      | 6. access_token pa_… (1 day), refresh_token pr_…  |
      |                      |<--------------------------------------------------|
      |                      | 7. API calls: Authorization: Bearer pa_…          |
      |                      |-------------------------------------------------->|

/oauth/authorize?client_id=cp_xxxx&redirect_uri=https%3A%2F%2Fpartner.example%2Fcallback&scope=read%20orders&state=<random>&code_challenge=<BASE64URL(SHA256(verifier))>&code_challenge_method=S256

import base64, hashlib, secrets
from urllib.parse import urlencode

CLIENT_ID = "cp_xxxx"
REDIRECT_URI = "https://partner.example/callback"

def start_connect(session: dict) -> str:
    """Returns the consent URL; keeps verifier and state in the session."""
    verifier = secrets.token_urlsafe(64)  # 86 chars from A-Z a-z 0-9 - _
    digest = hashlib.sha256(verifier.encode("ascii")).digest()
    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
    session["pkce_verifier"] = verifier
    session["oauth_state"] = secrets.token_urlsafe(32)
    return "/oauth/authorize?" + urlencode({
        "client_id": CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "scope": "read orders",
        "state": session["oauth_state"],
        "code_challenge": challenge,
        "code_challenge_method": "S256",
    })

import crypto from 'node:crypto';

export const CLIENT_ID = 'cp_xxxx';
export const REDIRECT_URI = 'https://partner.example/callback';

/** Returns the consent URL; keeps verifier and state in the session. */
export function startConnect(session) {
  const verifier = crypto.randomBytes(48).toString('base64url'); // 64 chars
  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
  session.pkceVerifier = verifier;
  session.oauthState = crypto.randomBytes(24).toString('base64url');
  const url = new URL('/oauth/authorize');
  url.search = new URLSearchParams({
    client_id: CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    scope: 'read orders',
    state: session.oauthState,
    code_challenge: challenge,
    code_challenge_method: 'S256'
  }).toString();
  return url.toString();
}

https://partner.example/callback?code=oc_xxxx&state=<your state>
https://partner.example/callback?error=access_denied&state=<your state>

curl -X POST https://cirrus.pocketful.in/v1/oauth/token \
  -u "$PARTNER_CLIENT_ID:$PARTNER_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=oc_xxxx \
  --data-urlencode redirect_uri=https://partner.example/callback \
  -d code_verifier=<verifier from the session>

import os, secrets
import requests

TOKEN_URL = "https://cirrus.pocketful.in/v1/oauth/token"
AUTH = (os.environ["PARTNER_CLIENT_ID"], os.environ["PARTNER_CLIENT_SECRET"])

def finish_connect(session: dict, query: dict) -> dict:
    """Handles GET https://partner.example/callback?code=…&state=…"""
    expected = session.pop("oauth_state", None)
    if not expected or not secrets.compare_digest(query.get("state", ""), expected):
        raise PermissionError("state does not match: start again")
    if "error" in query:  # access_denied: the user said no
        raise PermissionError(query["error"])
    reply = requests.post(TOKEN_URL, auth=AUTH, timeout=10, data={
        "grant_type": "authorization_code",
        "code": query["code"],
        "redirect_uri": "https://partner.example/callback",
        "code_verifier": session.pop("pkce_verifier"),
    })
    body = reply.json()
    if reply.status_code != 200:
        raise RuntimeError(f"{body['error']}: {body['error_description']}")
    return body  # store refresh_token encrypted, per user

import crypto from 'node:crypto';

export const TOKEN_URL = 'https://cirrus.pocketful.in/v1/oauth/token';
export const basic = Buffer.from(
  `${process.env.PARTNER_CLIENT_ID}:${process.env.PARTNER_CLIENT_SECRET}`
).toString('base64');

/** Handles GET https://partner.example/callback?code=…&state=… */
export async function finishConnect(session, query) {
  const expected = session.oauthState ?? '';
  delete session.oauthState;
  const given = String(query.state ?? '');
  if (!expected || given.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
    throw new Error('state does not match: start again');
  }
  if (query.error) throw new Error(query.error); // access_denied
  const reply = await fetch(TOKEN_URL, {
    method: 'POST',
    headers: { Authorization: `Basic ${basic}` },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: query.code,
      redirect_uri: 'https://partner.example/callback',
      code_verifier: session.pkceVerifier
    })
  });
  delete session.pkceVerifier;
  const body = await reply.json();
  if (!reply.ok) throw new Error(`${body.error}: ${body.error_description}`);
  return body; // store refresh_token encrypted, per user
}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "pa_…",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "pr_…",
  "scope": "read orders"
}

curl -X POST https://cirrus.pocketful.in/v1/oauth/token \
  -u "$PARTNER_CLIENT_ID:$PARTNER_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=pr_xxxx

def refresh(refresh_token: str) -> dict:
    """Save the new refresh token first: reuse after 30 s disconnects the user."""
    reply = requests.post("https://cirrus.pocketful.in/v1/oauth/token", auth=AUTH, timeout=10, data={
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
    })
    body = reply.json()
    if reply.status_code == 400 and body["error"] == "invalid_grant":
        raise PermissionError("connection ended: ask the user to connect again")
    reply.raise_for_status()
    return body  # save body["refresh_token"] before using the new access token

/** Save the new refresh token first: reuse after 30 s disconnects the user. */
export async function refresh(refreshToken) {
  const reply = await fetch('https://cirrus.pocketful.in/v1/oauth/token', {
    method: 'POST',
    headers: { Authorization: `Basic ${basic}` },
    body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken })
  });
  const body = await reply.json();
  if (reply.status === 400 && body.error === 'invalid_grant') {
    throw new Error('connection ended: ask the user to connect again');
  }
  if (!reply.ok) throw new Error(`${body.error}: ${body.error_description}`);
  return body; // save body.refresh_token before using the new access token
}

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
  "error": "invalid_grant",
  "error_description": "code_verifier does not match"
}

curl "https://cirrus.pocketful.in/v1/portfolio/positions" \
  -H "Authorization: Bearer pa_xxxx"