Partner sign-in (OIDC)
How an integration partner connects a SureBright merchant to its application with OpenID Connect: pushed authorization requests, consent, token exchange, scopes and claims.
SureBright is an OpenID Connect provider for integration partners. A merchant signs in to SureBright once, approves your application for one or more of their store locations, and you receive tokens plus an sbAccountId that identifies the connection. From then on you create and cancel contracts for that merchant with your own API key and the sbAccountId; see Request conventions.
Issuer: https://{HOST_NAME}/site-platform/api/v1/sso. Every endpoint below is relative to it. Responses carry Cache-Control: no-store.
Before you start#
SureBright registers your application and gives you a client_id. Registration fixes:
the client type:
CONFIDENTIAL(server-side, has a client secret) orPUBLIC(browser-based, no secret, calls must come from a registered origin);the redirect URIs you may use (HTTPS, or
http://localhostfor development);the scopes you may request (see below);
a display name and provider label the merchant sees on the consent screen.
Only the authorization code flow with PKCE (S256) and pushed authorization requests is supported. Check the live values with the discovery document.
Flow#
Push the authorization request
POST /parwith your client credentials and the request parameters. SureBright stores the request for 60 minutes and returns arequest_uriand a ready-madeauthorization_url.Send the merchant to SureBright
Redirect the merchant to
authorization_url(GET /authorize?client_id=...&request_uri=...). SureBright answers302to its own sign-in and consent page. The merchant signs in, must be an owner or administrator of their SureBright organization, picks the locations to connect, and approves or declines.Receive the code
Approval redirects to your
redirect_uriwithcodeandstate. A decline redirects witherror=access_denied,error_description=The merchant declined the connectionandstate. The code is single use and expires after 5 minutes.Exchange the code
POST /tokenwith the code, yourcode_verifierand client credentials. You receive an access token, an ID token and the merchant'ssbAccountId.
POST /par#
Client authentication: confidential clients send Authorization: Basic base64(client_id:client_secret) or client_id and client_secret in the form body. Public clients send client_id only and must include an Origin header that matches a registered origin.
Body is application/x-www-form-urlencoded or JSON:
code.code_verifier, 43 to 128 characters.S256.openid and only scopes your client is registered for.email, fullName, businessName, businessPhone (strings, trimmed to 200 characters) to pre-populate SureBright's sign-up form for a merchant who has no SureBright account yet. May be sent as a JSON string.curl -X POST https://{HOST_NAME}/site-platform/api/v1/sso/par \
-u '{client_id}:{client_secret}' \
-d response_type=code \
-d redirect_uri=https://app.example-pos.com/surebright/callback \
-d state=9f2c1b7e4a6d8c3f0e5b2a7d \
-d nonce=4b8e2d6a1c9f7e3b5d0a8c2e \
-d code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM \
-d code_challenge_method=S256 \
-d 'scope=openid profile email merchant.read sales.write' \
-d external_tenant_id=tenant_48213Returns 201:
request_uristringurn:ietf:params:oauth:request_uri:...expires_ininteger3600.authorization_urlstringGET /authorize#
GET /authorize?client_id={client_id}&request_uri={request_uri}. Responds 302 to SureBright's consent page, or an OAuth error (invalid_request_uri when the request is unknown, used or expired; invalid_client when your application is no longer active).
POST /token#
Same client authentication as /par.
authorization_code.redirect_uri from /par.{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
"token_type": "Bearer",
"expires_in": 900,
"scope": "openid profile email merchant.read sales.write",
"sbAccountId": "sb_int_3f9d2c7b-1a4e-4c2b-9f6d-8a1e4b7c2d10",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
}Both tokens are RS256 JWTs signed with the key published at /jwks, valid for 15 minutes, with aud equal to your client_id. The exchange fails with invalid_grant if the code was already used, the verifier does not match, the merchant's approval cannot be confirmed, or the connection has since been revoked, re-scoped or lost one of its locations. Store sbAccountId and the locations claim; they do not expire with the token.
Scopes#
Claims#
Both tokens carry iss, sub, aud, exp, iat, jti, client_id, scope and token_use (access or id). The ID token adds nonce and at_hash. With merchant.read, quotes.write or sales.write granted, both tokens also carry:
GET /userinfo#
Authorization: Bearer {access_token}. Returns sub, email, name, sb_member_id, store_parent_id, locations and sbAccountId (claims absent from the token are null). 401 invalid_token with WWW-Authenticate: Bearer realm="SureBright Partner OIDC" when the token is missing, expired or your application is inactive.
Discovery and keys#
GET /.well-known/openid-configurationlistsauthorization_endpoint,pushed_authorization_request_endpoint,token_endpoint,userinfo_endpoint,jwks_uri,response_types_supported: ["code"],grant_types_supported: ["authorization_code"],id_token_signing_alg_values_supported: ["RS256"],token_endpoint_auth_methods_supported: ["none", "client_secret_basic", "client_secret_post"],scopes_supported,code_challenge_methods_supported: ["S256"],request_uri_parameter_supported: trueandrequire_pushed_authorization_requests: true.GET /jwksreturns the signing key (kid,use: sig,alg: RS256). Cache it and refresh on an unknownkid.
GET /partner/requests//presentation#
Public. Returns what SureBright's consent page shows for a pending request, so you can render a matching landing page if you host one. requestId is the last segment of request_uri.
{ "isError": false, "data": { "client": { "clientId": "example-pos", "name": "Example POS", "provider": "EXAMPLE_POS" }, "prefill": { "email": "owner@example.com" }, "expiresIn": 3600 } }404 invalid_request once the request has been approved, declined or has expired.
Portal session endpoints#
GET /session and POST /logout belong to SureBright's own portals. /session reads the portal session cookie or a portal bearer token and returns authenticated with the member's sbMemberId, storeParentId, emailId, fullName, role, shop, idp and isSbAdmin, or {"authenticated": false}; a partner access token is not a portal token and returns authenticated: false. /logout clears the portal session cookies and returns {"success": true}. You do not need either for a partner integration.
Errors#
All errors are {"error": "...", "error_description": "..."}.