Appearance
Federation flow for banks
In federation, a trusted partner — in practice a bank or payment provider — vouches for its user. It sends Salaxy a signed message describing the user and, where relevant, the company; Salaxy creates the company account, or uses an existing account that has authorised you, and returns the user with an access token.
A federation provider must be committed to strong authentication (bank-ID level) and have signed a contract with Salaxy — in practice banks and payment providers that follow Finnish KYC rules. Interested? Contact Salaxy's customer service or sales.
Examples use test-* hosts — see Environments for demo and production.
Prerequisites
- Federation provider role. In production, only accounts marked as federation providers can use federation. Salaxy's back office sets the role after the contract is signed. In test, any account can currently use federation — this may change without notice, so tell Salaxy if you plan to use it.
- A certificate for the federation provider account, and its password — the same kind of Salaxy-issued certificate as in the impersonation flow, one per environment.
2. The federation message
The message is based on the OpenID Connect UserInfo response. It describes the end-user with the standard claims, plus three Salaxy claims: company, person and app.
Token claims
Borrowed from the OpenID Connect ID token, so that Salaxy can check the message:
| Member | Type | Description |
|---|---|---|
aud | string | Required. The federation endpoint: https://test-secure.salaxy.com/security/federation in test |
exp | number | Required. Expiry time, in seconds since the epoch |
iss | string | The issuer. Not checked |
Standard claims
| Member | Type | Description |
|---|---|---|
sub | string | Identifier for the end-user at the issuer |
name | string | Full name. Not used: Salaxy uses given_name and family_name |
given_name | string | Given name(s) |
family_name | string | Surname(s) |
picture | string | URL of the profile picture |
email | string | Preferred email address. Used only when email_verified is true |
email_verified | boolean | Whether the email address has been verified |
birthdate | string | Birthday, if the personal identity code is not known. Workers only |
locale | string | Locale, as a BCP 47 language tag |
phone_number | string | Preferred telephone number |
phone_number_verified | boolean | Whether the phone number has been verified |
address | object | Preferred postal address (formatted and region are accepted but not used) |
updated_at | number | When the information was last updated, in seconds since the epoch |
middle_name, nickname, preferred_username, profile, website, gender and zoneinfo are accepted but not used.
Salaxy claims
| Member | Type | Description |
|---|---|---|
https://salaxy.com/federation/person | object | Personal account data |
https://salaxy.com/federation/app | object | Application and session data: return links and state |
https://salaxy.com/federation/company | object | Company account data |
person
| Member | Type | Description |
|---|---|---|
can_sign_company | boolean | The user may sign on behalf of the company or association. Accepted but not currently used |
personal_id | string | Finnish personal identity code, for digital signature |
app
| Member | Type | Description |
|---|---|---|
return_link | string | Success URL: link back to your application; the token is added to it |
cancel_link | string | Cancel URL: link back in case of an error or cancel |
state | object | Your own data, as string values. It comes back to your success or cancel URL as state (Base64-encoded JSON). custom is an older name for the same member |
role | string | owner or noAccess. Accepted but not currently used |
company
| Member | Type | Description |
|---|---|---|
as_company | boolean | If true, the authorisation is for a company account and the root claims describe the user acting for it. If false, company is ignored |
business_id | string | Business ID, e.g. FI12345678 or 12345678 |
type | string | fiOy (limited company), fiTm (sole trader), fiRy (registered association), fiYy (other Finnish company or association) |
name | string | Company name, as in the trade register — shown on calculations, reports and invoices |
picture | string | URL of an image file (PNG preferred, square) for the company logo |
email | string | Email for salary-payment matters. Used only when email_verified is true |
email_verified | boolean | Whether the email has been verified |
phone_number | string | Telephone for salary-payment matters |
phone_number_verified | boolean | Whether the phone number has been verified |
address | object | Postal address for salary-payment matters |
proxy_partner | string | The primary partner account for a new company. You must be authorised to that partner, or be it |
partner_account_id | string | The account id at your site. If set, the authorisation is restricted to that one account |
3. Sign it as a JWT
Sign the message as a JWT with the certificate, RS256, with the certificate in the header: x5c as an array with exactly one item, and x5t as its thumbprint. In Node.js, jsonwebtoken; the current site has a C# example.
4–6. Send it
Send the user's browser to the federation endpoint on the API host — https://test-secure.salaxy.com/security/federation?token=<token> in test, by GET or POST. Salaxy looks for an existing account by business ID (company.business_id, when company.as_company is true) or personal identity code (person.personal_id):
- A new company account — the normal case — is created, and your account is automatically authorised to it.
- An existing account that has authorised you — the user gets a token for it.
- An existing company account that has not authorised you — the browser goes to your cancel URL with
error=access_denied. Theerror_description(in Finnish) tells the user to sign in to Salaxy, authorise your service and try again. - A personal account that does not exist yet, or has not authorised you, goes to a Salaxy onboarding page first.
The browser then returns to your success URL with the token in the URL fragment — #access_token=…&token_type=bearer&state=… — or to your cancel URL with #error=…&error_description=…. Validation errors also go to the cancel URL, with error=invalid_request and the failed fields listed (in Finnish).
7. Use the token
Browser JavaScript sets the token as the Bearer token on each Salaxy API call. See Tokens.
Other federation flows
Two alternatives are partly implemented but not in use, and not documented: the full OpenID Connect flow, if you already run an OpenID Provider, and SAML — either a full SAML SSO profile with you as identity provider, or just the signed response message. Ask Salaxy if you would rather use one of these.

