Refersion Authentication

generated: '2026-08-13'
method: searched
source: >-
  https://www.refersion.dev/reference/order-tracking-overview and the provider-published OpenAPI
  embedded in the ReadMe reference pages (harvested to
  openapi/_original/refersion-rest-api-readme-harvest.json)
name: Refersion Authentication
description: >-
  Refersion authenticates the REST API and the inbound order-tracking webhook with a static
  public/secret key PAIR sent as two custom request headers. There is no OAuth 2.0, no OpenID
  Connect, no bearer token, no mutual TLS and no token exchange of any kind. Note that the
  published OpenAPI declares NO `securitySchemes` and NO `security` block — the credentials are
  modelled as ordinary required header PARAMETERS, so automated tooling that reads only
  securitySchemes will conclude this API is unauthenticated. That is a real defect in the
  contract, not a gap in this profile.
schemes:
- name: Refersion-Public-Key
  type: apiKey
  in: header
  required: true
  description: >-
    Public half of the key pair, identifying the Refersion account. Example prefix published in the
    spec is `pub_`. Also used alone, client-side, as `r.pubKey` in the refersion.js tracking
    snippet.
  example_prefix: pub_
  spec_component: '#/components/parameters/Refersion-Public-Key'
- name: Refersion-Secret-Key
  type: apiKey
  in: header
  required: true
  description: >-
    Secret half of the key pair. Server-side only — it never appears in any documented client-side
    snippet.
  example_prefix: sec_
  spec_component: '#/components/parameters/Refersion-Secret-Key'
applies_to:
- surface: REST API v2
  base_url: https://api.refersion.com/v2
  headers:
  - Refersion-Public-Key
  - Refersion-Secret-Key
  - Content-Type
  note: All 15 published operations require both keys plus Content-Type application/json.
- surface: Inbound order-tracking webhook
  base_url: https://inbound-webhooks.refersion.com
  headers:
  - Refersion-Public-Key
  - Refersion-Secret-Key
  docs: https://www.refersion.dev/reference/webhook-tracking
- surface: Client-side tracking (refersion.js)
  headers: []
  note: Public key only, assigned to r.pubKey in the browser. The secret key is never exposed here.
- surface: GraphQL API
  base_url: https://api.refersion.com/graphql
  note: >-
    Documented as available but the endpoint returns HTTP 403 {"message":"Forbidden"} to an
    anonymous POST, so the credential form could not be confirmed by probe. The overview page
    documents no auth mechanism of its own.
  probed:
    url: https://api.refersion.com/graphql
    http_status: 403
    checked: '2026-08-13'
key_management:
  location: Account > Settings > Refersion API
  url: https://www.refersion.com/base/settings/integrations/api
  self_service: true
  rotation: >-
    Merchants may use an existing key set or create a new set from the dashboard. No documented
    programmatic rotation, no expiry, no scoping and no per-key permissioning.
  scopes: none
  expiry: none
failure_modes:
- status: 401
  body: '{"error": "Invalid API credentials (error 2)."}'
  description: >-
    Unauthorized — API keys are incorrect. Defined once as
    #/components/responses/401_Error and $ref'd by every operation.
gaps:
- The OpenAPI declares no securitySchemes / security, only header parameters.
- No OAuth 2.0 or OIDC; therefore no scopes artifact is produced for this provider.
- Keys are long-lived, unscoped and account-wide — a leaked pair grants the full API surface.
- The dedicated /reference/authentication docs page exists but is an unedited ReadMe placeholder.