---
title: "Partner sign-in (OIDC)"
description: "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](/api-reference/endpoint/order/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

<Steps>
  <Step title="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`.
  </Step>
  <Step title="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.
  </Step>
  <Step title="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.
  </Step>
  <Step title="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`.
  </Step>
</Steps>

## 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:

<ParamField body="response_type" type="string" required>Must be `code`.</ParamField>
<ParamField body="redirect_uri" type="string" required>One of your registered redirect URIs.</ParamField>
<ParamField body="state" type="string" required>Opaque value you check on return. 16 to 512 characters.</ParamField>
<ParamField body="nonce" type="string" required>Returned in the ID token. 16 to 512 characters.</ParamField>
<ParamField body="code_challenge" type="string" required>PKCE challenge, base64url SHA-256 of your `code_verifier`, 43 to 128 characters.</ParamField>
<ParamField body="code_challenge_method" type="string" required>Must be `S256`.</ParamField>
<ParamField body="scope" type="string" required>Space-separated scopes. Must include `openid` and only scopes your client is registered for.</ParamField>
<ParamField body="external_tenant_id" type="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.</ParamField>
<ParamField body="external_user_id" type="string">Optional, confidential clients only. The user in your system who started the connection, at most 200 characters.</ParamField>
<ParamField body="prefill" type="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.</ParamField>

```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`:

<ResponseField name="request_uri" type="string">`urn:ietf:params:oauth:request_uri:...`</ResponseField>
<ResponseField name="expires_in" type="integer">Seconds the request stays valid. `3600`.</ResponseField>
<ResponseField name="authorization_url" type="string">The URL to send the merchant to.</ResponseField>

## 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`.

<ParamField body="grant_type" type="string" required>Must be `authorization_code`.</ParamField>
<ParamField body="code" type="string" required>The code from the redirect.</ParamField>
<ParamField body="redirect_uri" type="string" required>Must equal the `redirect_uri` from `/par`.</ParamField>
<ParamField body="code_verifier" type="string" required>Your PKCE verifier, 43 to 128 characters.</ParamField>

```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

| Scope | Grants |
|---|---|
| `openid` | Required. Issues the ID token with `sub` (the approving member). |
| `profile` | `name` claim. |
| `email` | `email` claim (`email_verified` in the ID token). |
| `merchant.read` | The merchant claims below. |
| `quotes.write` | Request quotes on behalf of the merchant, plus the merchant claims. |
| `sales.write` | Create 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:

| Claim | Meaning |
|---|---|
| `sbAccountId` | The connection ID you send as `sbAccountId` on contract calls. |
| `locations` | The locations the merchant authorised: `locationId`, `name`, `address` (`addressLine1`, `addressLine2`, `city`, `state`, `zipCode`, `country`). Use a `locationId` as `sbStoreId`. |
| `store_parent_id` | The merchant's SureBright organization. |
| `sb_member_id` | The member who approved. |
| `external_tenant_id` | Your tenant ID from `/par` (public clients: `surebright:` followed by the organization ID). |
| `grant_revision`, `consent_version` | Change 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/{requestId}/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": "..."}`.

| Status | `error` | When |
|---|---|---|
| `400` | `invalid_request` | A `/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`) |
| `400` | `unsupported_response_type`, `unsupported_grant_type` | Anything other than `code` / `authorization_code` |
| `400` | `invalid_scope` | `openid` missing, or a scope your client is not registered for |
| `400` | `invalid_request_uri` | `/authorize` with an unknown, used or expired `request_uri` |
| `400` | `invalid_grant` | Code invalid, expired, reused, verifier mismatch, or connection no longer active |
| `401` | `invalid_client` | Client authentication failed, a public client sent a secret, or the browser `Origin` is not registered. `WWW-Authenticate: Basic realm="SureBright Partner OIDC"` |
| `401` | `invalid_token` | `/userinfo` without a valid bearer token |
| `503` | `temporarily_unavailable` | Partner sign-in is not configured in this environment or the client registry is unreachable; retry later |
