API authentication

Three ways to authenticate with the MeerPartners API: human sign-in via MeerID OIDC, JWT Bearer for the cabinet, and HMAC over an API key for server-to-server integrations. When to use which.

MeerPartners has three authentication methods — each for its own purpose. People sign in via MeerID, the browser cabinet calls the API with a JWT, and server-to-server integrations (postback, SSO) sign requests with HMAC over the API key secret.

Which method when

MeerID OIDC — human sign-in

Signing in to MeerPartners is only via MeerID, the single OIDC SSO of the Meer ecosystem. The platform has no registration, passwords or OTP of its own. A person signs in to MeerID, the platform receives a verified identity and exchanges it for a local JWT pair.

This is the public first-session endpoint: the MeerID browser SDK returns either a code + PKCE (popup/redirect) or a signed idToken + nonce (FedCM), and the platform returns an access_token / refresh_token.

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 900,
  "user": {
    "user_id": 42,
    "email": "a@b.io",
    "display_name": "Neo",
    "is_affiliate": false,
    "affiliate_id": null,
    "memberships": []
  }
}

This is handled by the MeerPartners portal — you do not need to embed this flow into your own integration. If you need to authorize your own users inside the affiliate program without MeerID, use token-exchange, not OIDC. For how people sign in, see Registration & sign-in.

JWT Bearer — cabinet requests

After sign-in the portal talks to the core API with a local JWT. The cabinet endpoints (/api/v1/aff/*, /api/v1/merchant/*, /api/v1/auth/me) accept the token in the standard header:

Authorization: Bearer <access_token>

Refresh tokens are rotated: on POST /api/v1/auth/refresh the old token is consumed and a new pair is issued. Reusing an already-used refresh token outside the short grace window → TOKEN_REVOKED (401).

API key + HMAC — server-to-server integrations

For S2S calls (your business server → the platform) JWT is not used — the request is signed with HMAC-SHA256 over the API key secret. Signed this way are:

• Conversion postback — POST /api/v1/postback (requires the postback scope);
• Token-exchange / SSO — POST /api/v1/auth/token-exchange (requires the sso scope).

Each request carries four headers and a signature of the request string:

X-Api-Key-Id: <key_id>
X-Tenant-Id: <tenant_id>        # optional; if set, must match the key's tenant
X-Timestamp: 1717200000          # epoch seconds, ±300 s window
X-Signature: <hex(HMAC_SHA256(secret, signing_string))>

The signing_string is assembled like this:

{METHOD}\n{PATH}\n{X-Timestamp}\n{SHA256_hex(raw_body)}

The body enters the signature as a hash — this protects integrity: the amount or fields of the order cannot be changed after signing. The platform verifies the signature in constant time and checks the freshness of X-Timestamp (anti-replay).

The full algorithm with a worked example, along with scopes, key rotation and revocation, is on the next page.

What's next