Skip to content

Impersonation flow for SSO ​

Impersonation lets your server sign in to the Salaxy API as another account — a customer that has already authorised your product. It is how single sign-on works: your users sign in to your product, and your server gets a Salaxy token for them. It is also the flow behind white label.

Technically it is an OAuth 2.0 JWT authorisation grant (RFC 7523), grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer.

Examples use test-* hosts — see Environments for demo and production.

Impersonation flow for SSOOnce, create a certificate in Salaxy. Then: the user signs in to your product; your server builds and signs a JWT, posts it to the Salaxy token endpoint, and receives an access token for the user; API calls carry the token as a Bearer token.Your serverBrowserSalaxy1 · Once: create a certificate in Salaxy (Settings → Authorisations)2 · The user signs in to your product3 · Build and sign a JWT (RS256)4 · POST /oauth2/token — jwt-bearer grant5 · access_token for the user6 · Token to the browser (optional)7 · API calls: Authorization: Bearer …
Numbers match the steps below. Your server can also keep the token and call the API itself.

1. Create a certificate — once ​

  1. Sign in to the Salaxy web application — in test, test.palkkaus.fi.
  2. Go to Settings → Authorisations.
  3. Create a new digital certificate and download it:
    • .pfx — private key and certificate together (.NET, Java …)
    • .pem — key and certificate as separate files (Node.js, Python …)

The API does the same: POST /v03/api/accounts/certificate returns a .pfx, POST /v03/api/accounts/certificate/pem a ZIP with the .crt, .key and .pem files. GET /v03/api/accounts/certificate lists your certificates and DELETE /v03/api/accounts/certificate/{id} revokes one. An account can hold several certificates, so you can rotate without downtime: add the new one, switch, then revoke the old one.

  • One certificate per environment. Test and demo certificates are signed by a different root than production ones: a test certificate fails in production, and the other way round.
  • Any account can create a certificate; no partner role is needed.

Keep the private key secret

It signs your JWT assertions: anyone who has it can act for your customers. If it leaks, revoke the certificate.

2–3. Build and sign the JWT ​

When a user signs in to your product, your server builds a JWT.

Header

ParameterDescription
algRS256
typJWT
x5cYour certificate (base64), as an array with exactly one item. Salaxy identifies your account by this certificate

Claims

ClaimDescription
issThe issuing application, for example your account id. Not checked
subThe Salaxy account id you act for: the customer that has authorised you (e.g. FI14POYT0002345678) — not a business ID or email. In a company integration, set it to your own account id to sign in as yourself
audThe token endpoint: https://test-secure.salaxy.com/oauth2/token in test
expRequired. Expiry time, e.g. 5 minutes from now
salaxy_user (optional){ "email": "…" } — the person acting through your system. It lands in the token's credential_id claim; the token's email claim keeps the impersonated account's own address. Omit it to act purely as the account
salaxy_proxy_act (optional)A proxy partner account between you and sub, when you are not directly authorised on sub. Both hops — you → proxy → sub — are validated
json
{
  "iss": "FI00POY10000000000",
  "sub": "FI14POYT0002345678",
  "aud": "https://test-secure.salaxy.com/oauth2/token",
  "exp": 1731436800,
  "salaxy_user": { "email": "john.doe@example.com" }
}

Sign it with your private key, RS256. In Node.js with jsonwebtoken:

js
import fs from 'fs'
import jwt from 'jsonwebtoken'

const privateKey = fs.readFileSync('salaxy_private_key.pem')
const now = Math.floor(Date.now() / 1000)

const assertion = jwt.sign(
  {
    iss: 'FI00POY10000000000',
    sub: 'FI14POYT0002345678',
    aud: 'https://test-secure.salaxy.com/oauth2/token',
    salaxy_user: { email: 'john.doe@example.com' },
    iat: now,
    exp: now + 300,
  },
  privateKey,
  { algorithm: 'RS256' },
)

4–5. Exchange it for an access token ​

http
POST https://test-secure.salaxy.com/oauth2/token
Content-Type: application/json

{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "<signed JWT>"
}
json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Errors return HTTP 400 with error: "invalid_request" and an error_description — for example an unknown sub, an expired assertion or a certificate Salaxy did not issue. When you are not authorised to sub (or to the salaxy_proxy_act account), the error also has an error_uri: a Salaxy page that tells the customer how to authorise you. In production that page works for trusted partners only.

json
{
  "error": "invalid_request",
  "error_description": "Requesting user is not allowed to impersonate account. (403 Forbidden: FI00POY10000000000 to FI14POYT0002345678).",
  "error_uri": "…/Security/AuthorizePartner/FI00POY10000000000?sub=FI14POYT0002345678"
}

6–7. Use the token ​

Your server calls the API with it, or passes it to the browser — for white label, into the iframe URL. See Tokens: lifetime, no refresh tokens, the invalid_token error.

Recording who acted: read the token's credential_id claim, not email, to learn which person acted through your system.

Example code in .NET, TypeScript / JavaScript and PHP: salaxy-demo-sso.

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.