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) or PUBLIC (browser-based, no secret, calls must come from a registered origin);

  • the redirect URIs you may use (HTTPS, or http://localhost for 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#

  1. Push the authorization request

    POST /par with your client credentials and the request parameters. SureBright stores the request for 60 minutes and returns a request_uri and a ready-made authorization_url.

  2. Send the merchant to SureBright

    Redirect the merchant to authorization_url (GET /authorize?client_id=...&request_uri=...). SureBright answers 302 to 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.

  3. Receive the code

    Approval redirects to your redirect_uri with code and state. A decline redirects with error=access_denied, error_description=The merchant declined the connection and state. The code is single use and expires after 5 minutes.

  4. Exchange the code

    POST /token with the code, your code_verifier and client credentials. You receive an access token, an ID token and the merchant's sbAccountId.

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:

stringrequired
Must be code.
stringrequired
One of your registered redirect URIs.
stringrequired
Opaque value you check on return. 16 to 512 characters.
stringrequired
Returned in the ID token. 16 to 512 characters.
stringrequired
PKCE challenge, base64url SHA-256 of your code_verifier, 43 to 128 characters.
stringrequired
Must be S256.
stringrequired
Space-separated scopes. Must include openid and only scopes your client is registered for.
string
Confidential clients: required. Your own identifier for the merchant's account in your system, at most 200 characters. One SureBright organization can be connected per tenant. Ignored for public clients.
string
Optional, confidential clients only. The user in your system who started the connection, at most 200 characters.
object
Optional. 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.
bash
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_48213

Returns 201:

request_uristring
urn:ietf:params:oauth:request_uri:...
expires_ininteger
Seconds the request stays valid. 3600.
authorization_urlstring
The URL to send the merchant to.

GET /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.

stringrequired
Must be authorization_code.
stringrequired
The code from the redirect.
stringrequired
Must equal the redirect_uri from /par.
stringrequired
Your PKCE verifier, 43 to 128 characters.
json
{
  "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#

ScopeGrants
openidRequired. Issues the ID token with sub (the approving member).
profilename claim.
emailemail claim (email_verified in the ID token).
merchant.readThe merchant claims below.
quotes.writeRequest quotes on behalf of the merchant, plus the merchant claims.
sales.writeCreate and cancel contracts on behalf of the merchant, plus the merchant claims.

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:

ClaimMeaning
sbAccountIdThe connection ID you send as sbAccountId on contract calls.
locationsThe locations the merchant authorised: locationId, name, address (addressLine1, addressLine2, city, state, zipCode, country). Use a locationId as sbStoreId.
store_parent_idThe merchant's SureBright organization.
sb_member_idThe member who approved.
external_tenant_idYour tenant ID from /par (public clients: surebright: followed by the organization ID).
grant_revision, consent_versionChange when the merchant re-approves or SureBright updates the consent text.

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-configuration lists authorization_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: true and require_pushed_authorization_requests: true.

  • GET /jwks returns the signing key (kid, use: sig, alg: RS256). Cache it and refresh on an unknown kid.

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.

json
{ "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": "..."}.

StatuserrorWhen
400invalid_requestA /par parameter is missing or malformed (the description names it, for example state must contain between 16 and 512 characters, PKCE S256 code_challenge is required, redirect_uri is not registered for this client, external_tenant_id is required)
400unsupported_response_type, unsupported_grant_typeAnything other than code / authorization_code
400invalid_scopeopenid missing, or a scope your client is not registered for
400invalid_request_uri/authorize with an unknown, used or expired request_uri
400invalid_grantCode invalid, expired, reused, verifier mismatch, or connection no longer active
401invalid_clientClient authentication failed, a public client sent a secret, or the browser Origin is not registered. WWW-Authenticate: Basic realm="SureBright Partner OIDC"
401invalid_token/userinfo without a valid bearer token
503temporarily_unavailablePartner sign-in is not configured in this environment or the client registry is unreachable; retry later