Customer connections
Customer-controlled linking: verified claims, consent, PKCE, subject credentials, field scopes, and revocation.
Correlation never grants access
An external platform connects an account it already controls to a SMOKESTACK customer only after that customer authenticates with SMOKESTACK and approves the connection. This is not a directory, tenant-wide lookup, marketing export, or shortcut into another product.
Email, phone, legal name, date of birth, and address are correlators, not authenticators. A private match may identify a possible relationship; only customer-controlled authorization creates permission. Publishing this design does not activate the flow.
Prepare verified claims and a redirect
Use an opaque ext_… externalSubject for the partner account—not an email address, phone number, or SMOKESTACK customer ID. The intent requires verified email or phone, verified legal name, and verified date of birth. Address evidence is optional. Each claim carries its verification time and the contract's permitted verification method.
Schema acceptance alone is not trust. Partner admission, verification method, freshness, confidence, and risk still need private evaluation. Future-dated, stale, or insufficient claims cannot create authority or produce a match-specific response.
Prepare a pre-registered HTTPS redirect, state, and an S256 PKCE challenge. Browser code receives the authorization redirect and code only; subject access and refresh tokens stay on the partner backend. Use the exact request schema in the pinned reference rather than an unrelated OAuth library's assumed wire format.
Connection flow
- The admitted partner creates an intent for its own external subject, verified claims, purpose, requested scopes, registered redirect, state, and PKCE challenge.
- SMOKESTACK evaluates correlation privately. Zero, one, or multiple candidates all produce the same 202 AWAITING_CUSTOMER_AUTHORIZATION response with an authorization URL and expiry.
- The customer follows that URL, authenticates on a SMOKESTACK-controlled surface, and reviews the partner, purpose, fields, duration, and scopes.
- Absent or ambiguous correlation is resolved inside the customer or authorized-retailer workflow. Possible matches are never shown to the partner.
- Approval creates an auditable, revocable grant and a random, persisted pairwise subject for the tenant, partner assignment, and canonical customer relationship.
- The registered redirect receives a single-use authorization code only after approval. The partner backend exchanges it with the PKCE verifier and matching redirect URI.
- The partner calls only the approved /me resources with the subject access token, not with its partner-service credential.
- The customer can revoke the connection. Refresh stops immediately and every subject access checks the active grant version.
Two credentials, different authority
partnerServiceBearer reaches capabilities, intent creation, and subject-token exchange. customerSubjectBearer reaches only that pairwise subject's approved /me resources. A partner-service credential by itself cannot read a customer profile.
A /me request uses one Authorization bearer: the customer-subject token. Partner and assignment binding are token claims, not a second Authorization header. The subject token's maximum lifetime is 900 seconds in this revision; refresh rotation, grant binding, and replay checks remain mandatory.
The token endpoint accepts the contract's authorization_code or refresh_token grantType shapes. Follow the generated request schema and keep tokens server-side; this documentation does not issue credentials or provide an interactive token exchange.
Consent and field-level scopes
Request only the fields required for the stated purpose. Basic profile access does not include contact, birth date, or medical eligibility. Fields without an active approved scope are omitted, not silently added to a broader response.
- customer.profile.basic: pairwise subject and approved basic profile/name data.
- customer.profile.contact: approved email and phone fields.
- customer.profile.birth_date: approved date of birth.
- customer.medical_eligibility.read: separately consented, normalized medical eligibility and freshness only.
Non-enumeration includes failure behavior
There is no customer list, search, candidate lookup, masked contact, match count, or intent-status polling endpoint. Creating an intent cannot notify a privately matched customer out of band. Timing, redirects, callbacks, retry behavior, and delivery behavior must not reveal whether a match exists.
Customer denial, absent or ambiguous correlation, expiration, and risk denial produce the same access_denied authorization result. Invalid, expired, replayed, or denied exchange artifacts collapse to invalid_grant without match-specific detail. Do not turn these responses into a customer-existence test.
Pairwise identity, merge lineage, and revocation
The subject is unique to the tenant, partner assignment, and canonical customer relationship. It is not a database customer ID or a general cross-partner tracking identifier. Linking and matching do not independently authorize data access.
The durable grant records the assignment, external and pairwise subjects, approved scopes, purpose, consent version, approval time, expiry, grant version, and revocation. Customer merge lineage preserves the authorized relationship without revealing the old or new internal customer identifier.
Customers must be able to see and revoke active connections in a first-party SMOKESTACK account surface. Support-only withdrawal is not sufficient. Self-revocation targets the grant that minted the presented subject credential; it cannot select another customer's connection.
Medical eligibility is not purchase allowance
The sensitive read describes the MEDICAL_CANNABIS program, jurisdiction, normalized eligibility status, checkedAt, and validUntil. It does not initiate state verification; Compliance owns verification and its evidence.
It exposes no card number or scan, provider payload, evidence hash, internal verification record, allowance, allotment, or remaining quantity. Eligibility and purchase allowance are different facts. Quantity cannot be published without an authoritative subject, unit, basis, and freshness contract.
Domain boundaries remain intact
Orders belong to Commerce, payment methods to Payments, and loyalty to its owning product—even if they later accept a customer grant. Medical eligibility is not purchase allowance. Customer Connections is not a marketing export, and medical status is not an audience segmentation field.
The old, never-enabled Ecom customer-links placeholder is retired. A storefront credential is not customer-link authority; the Customer Connections intent flow is the sole published planned linking contract. No /me/orders, /me/payment-methods, or /me/loyalty operation is introduced here.
What must exist before activation
This guide and its reference are a design and validation surface, not permission to call a live endpoint. Activation separately requires customer authentication and consent, private matching and risk controls, durable grants and pairwise identity, code/refresh/replay handling, auditable reads and decisions, bounded rate limits, and environment-owned deployment and health proof.
Privacy, consent, retention, security, and abuse review must also be complete. Publishing a schema or this guide does not establish legal certification or replace those operational prerequisites.
Reference for this guide
Read the complete 2026-08-24 contract →
- Read Customer Connections contract capabilitiesPlanned contract
- Create a customer-controlled connection intentPlanned contract
- Exchange an authorization code or rotate a refresh tokenPlanned contract
- Read the connected customer's granted profilePlanned contract
- Read separately consented medical eligibilityPlanned contract
- Revoke the current customer connectionPlanned contract