Appearance
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.
1. Create a certificate — once
- Sign in to the Salaxy web application — in test, test.palkkaus.fi.
- Go to Settings → Authorisations.
- 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
| Parameter | Description |
|---|---|
alg | RS256 |
typ | JWT |
x5c | Your certificate (base64), as an array with exactly one item. Salaxy identifies your account by this certificate |
Claims
| Claim | Description |
|---|---|
iss | The issuing application, for example your account id. Not checked |
sub | The 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 |
aud | The token endpoint: https://test-secure.salaxy.com/oauth2/token in test |
exp | Required. 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.

