# 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](https://code.salaxy.com/white-label/how-it-works.md).

Technically it is an OAuth 2.0 **JWT authorisation grant** ([RFC 7523](https://tools.ietf.org/html/rfc7523)), `grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer`.

Examples use `test-*` hosts — see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Once, 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. (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](https://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**

| 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](https://code.salaxy.com/security/rest-authentication.md#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](https://gitlab.com/salaxy/salaxy-demo-sso).
