Shopback Authentication

generated: '2026-08-02'
method: searched
source: >-
  derived from openapi/shopback-online-payments-openapi.yml securitySchemes,
  upgraded from https://docs.shopback.com/reference/getting-started-authentication,
  https://docs.shopback.com/reference/generating-hmac-signature,
  https://docs.shopback.com/docs/token-validity and
  https://docs.shopback.com/docs/online-payment-credentials
docs: https://docs.shopback.com/reference/generating-hmac-signature
summary:
  types: [http, hmac, apiKey]
  api_key_in: [header]
  oauth2_flows: []
  note: >-
    ShopBack publishes two distinct auth models, one per API. Only the Online
    Payments API declares a securityScheme in its OpenAPI; the In-Store Payments
    API models its credentials as required header parameters rather than a
    declared scheme, so the derived pass alone missed it.
schemes:
- name: bearer
  api: ShopBack Online Payments API
  type: http
  scheme: bearer
  bearerFormat: JWT
  description: Merchant JWT obtained from the merchant login operation.
  header: 'Authorization: Bearer <merchant_jwt>'
  token_endpoint: POST /auth/login
  token_endpoint_note: >-
    The published securityScheme description says "POST
    /merchant-gateway/auth/login", while the documented path item (operationId
    `login`) is /auth/login relative to the declared server. Recorded verbatim;
    not reconciled.
  credentials:
    username: Merchant ID
    password: Merchant Secret (separate sandbox and production values)
    issued_by: ShopBack for Business merchant portal, Settings → Generate credential
    portals:
    - https://business.shopback.sg/signin
    - https://business.shopback.my/signin
    docs: https://docs.shopback.com/docs/online-payment-credentials
    note: The Merchant Secret can only be viewed once, at generation time.
  token_lifetime: 8 hours
  guidance: ShopBack recommends generating a new token per transaction.
  sources:
  - openapi/shopback-online-payments-openapi.yml
  - https://docs.shopback.com/docs/token-validity
- name: SB1-HMAC-SHA256
  api: ShopBack In-Store Payments API
  type: hmac
  algorithm: HMAC-SHA256
  encoding: hex
  header: 'Authorization: SB1-HMAC-SHA256 <accessKeyId>:<hmacSignature>'
  additional_required_headers:
  - name: Date
    description: ISO-8601 UTC timestamp; must be byte-identical to the value used
      in the signature. Non-UTC offsets or roughly a minute of clock skew expire
      the signature.
  - name: Content-Type
    description: application/json
  signed_string_order:
  - HTTP method (uppercase)
  - request content type
  - ISO-8601 UTC date-time
  - fully qualified request path including query parameters
  - SHA-256 hex digest of the alphabetically key-sorted, stringified JSON body
  credentials:
    accessKeyId: identifier paired with the secret
    accessKeySecret: HMAC signing secret
    posId: one per terminal, kiosk, cashier register, app or website instance
    note: Sandbox and production credentials differ; production keys are issued at
      go-live.
  sources:
  - https://docs.shopback.com/reference/generating-hmac-signature
  - https://docs.shopback.com/reference/in-store-getting-started
  - openapi/shopback-in-store-payments-openapi.yml
- name: X-ShopBack-App-Token
  api: ShopBack Online Payments API (tokenized payments, client-side)
  type: apiKey
  in: header
  parameter_name: X-ShopBack-App-Token
  description: >-
    Short-lived JWT returned by the link-session endpoint. Passed by the merchant
    app as a custom header when opening the ShopBack consent page in an in-app
    browser (SFSafariViewController / Chrome Custom Tabs). Not a server-to-server
    credential.
  sources:
  - https://docs.shopback.com/reference/account-linking-1
  - openapi/shopback-online-payments-openapi.yml
bearer_tokens_of_record:
- name: paymentToken
  kind: long-lived user payment token
  description: >-
    Issued after a user completes the ShopBack consent flow; scoped to one user
    and one merchant channel. States LINKED / UNLINKED. Not an API credential —
    it is a payment instrument reference sent in the request body.
  docs: https://docs.shopback.com/reference/account-linking-1
oauth2:
  supported: false
  note: >-
    Account linking is OAuth-shaped (hosted consent page, single-use 60-second
    auth code, code-for-token exchange, revocation endpoint) but is not an OAuth
    2.0 profile: there is no authorization-server metadata, no scope model, no
    refresh token, and /.well-known/oauth-authorization-server returns 404 on
    every ShopBack host. No scopes/ artifact was written for this reason.
transport:
  https_required: true
  tls_minimum: TLS 1.2
  source: https://docs.shopback.com/docs/quickstart-api