Authorization flow

The SP/1 authorization flow adapts the OAuth 2.0 authorization-code pattern to person-to-business data grants. The resource owner is the subject; the scopes are registry fields; the “token” is a single-use share code redeemed server-side for a share.

Flow

Recipient page                Hub                          Subject
     │  1. authorize request   │                              │
     │  (client_id, fields,    │                              │
     │  purpose, duration,     │                              │
     │  origin, code_challenge)│                              │
     ├────────────────────────►│  2. authenticate + present   │
     │                         ├─────────────────────────────►│
     │                         │  3. explicit approval        │
     │                         │◄─────────────────────────────┤
     │  4. share_code (single  │                              │
     │     use, short TTL)     │                              │
     │◄────────────────────────┤                              │
     │  5. redeem: share_code +│                              │
     │     code_verifier       │                              │
     ├────────────────────────►│                              │
     │  6. share_id, fields,   │                              │
     │     fingerprint,        │                              │
     │     expires_at          │                              │
     │◄────────────────────────┤                              │

Requirements

The authorize request

• The request MUST name the exact fields requested (registry keys), a purpose (3–200 chars), a duration, and the capturing origin (URL).
• The request MUST carry a PKCE code_challenge: base64url, 43 chars, derived S256 from a client-held code_verifier. Plain PKCE MUST NOT be accepted.
• The hub MUST verify that origin belongs to the requesting client’s set of verified domains and MUST reject mismatches.

Consent presentation

• The hub MUST display the requesting business, the exact field list, the purpose, and the expiry before approval. Pre-checked or bundled approval MUST NOT be used.
• If the subject is unauthenticated, the hub MUST preserve the pending authorize intent through sign-in and return the subject to it (never to a generic landing page).

The share code

• Share codes MUST be single-use and short-lived. A second redemption attempt MUST fail.
• Redemption MUST present the code_verifier matching the original code_challenge (S256(code_verifier) == code_challenge).
• On success the hub returns share_id, the granted fields with values, the fingerprint, and expires_at.

Transport modes

Client environments differ; SP/1 defines three delivery modes:

Mode	Mechanism	Requirement
popup	Hub UI in a popup; result via postMessage	Sender origin MUST be validated
redirect	Full-page redirect; result via query params on return	redirect_uri origin MUST equal the server-validated origin; pending PKCE state MUST survive the round-trip (e.g. sessionStorage); result params MUST be scrubbed from the URL after resume
auto	Feature-detect: popup where supported, else redirect	Implementations SHOULD default to auto — most mobile platforms suppress popups

Return-to intent

When authentication interrupts an authorize flow, hubs MUST return the subject to the pending consent after sign-in. Return targets MUST be app-relative paths — cross-origin or protocol-relative (//) values MUST be rejected.

Accountless capture

For form-embedded consent without a subject account, see consent certificates: the same origin-pinning and evidence rules apply, but the flow is a single server capture call bound to the recipient’s verified domain.