Skip to content

REST authentication Finland ​

The Salaxy API uses OAuth 2.0 with JSON Web Tokens. Every flow ends the same way: you get an access token and send it as a Bearer token on each API call.

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

Which flow ​

FlowUse it forEnvironments
Password flowDevelopment and testing with your own test accountTest and demo; production only by manual registrationPassword flow
Impersonation flow for SSOYour server acts for a customer account that has authorised you — the flow for production integrations and white labelAllImpersonation
Federation flow for banksBanks and payment providers with strong authentication create or sign in to Salaxy accounts for their usersAll; production needs the Federation provider roleFederation
Partner-initiated account creationMaking sure a company account exists before onboarding — not a sign-in flow, used alongside SSO and federationAll; production needs the trusted partner roleAccount creation

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

Tokens ​

  • Endpoint: POST /oauth2/token on the API host — https://test-secure.salaxy.com/oauth2/token in test. The body can be JSON or application/x-www-form-urlencoded.

  • Success: HTTP 200 with access_token and token_type (bearer). There is no expires_in: read the token's exp claim if you need the expiry time.

  • Failure: HTTP 400 with an OAuth error — error (invalid_request or access_denied) and error_description. The grant types client_credentials and refresh_token return HTTP 501.

  • Use: send the token in the Authorization header on every call:

    http
    GET /v03/api/payroll
    Authorization: Bearer eyJhbGciOi...
  • Lifetime: currently 48 hours.

  • No refresh tokens. When a token expires, repeat the grant — the password grant or a new signed JWT.

  • Expired or invalid token: HTTP 401 with an empty body. The WWW-Authenticate header says why:

    http
    WWW-Authenticate: Bearer error="invalid_token", error_description="The token expired at '…'"
  • Claims you can read: account_row_id — the account the token acts for; credential_id — the person or credential acting; email; salaxy_partner — the partner the token was issued through; exp. Salaxy signs the token with its own key (HS256), so you cannot verify the signature — decode it only to read these claims.

The OpenAPI document declares no security scheme yet

The REST reference cannot show how to authenticate, and its Test Request cannot sign in, because the generated OpenAPI file has no securitySchemes. Until it does, use the flows on these pages to get a token and call the API from your own code.

Checklist ​

  • Your production server uses the impersonation flow with a signed JWT; the password flow is for development and testing.
  • Your private key stays on your server, never in a browser or a repository.
  • Every call sends the token as Authorization: Bearer <token>.
  • A 401 triggers one new token (repeat the grant) and one retry: there are no refresh tokens, and a token lasts about 48 hours.

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.