# 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](https://code.salaxy.com/get-started/environments.md) for demo and production.

## Which flow

| Flow | Use it for | Environments | |
|---|---|---|---|
| **Password flow** | Development and testing with your own test account | Test and demo; production only by manual registration | [Password flow](https://code.salaxy.com/security/password.md) |
| **Impersonation flow for SSO** | Your server acts for a customer account that has authorised you — the flow for production integrations and [white label](https://code.salaxy.com/white-label/how-it-works.md) | All | [Impersonation](https://code.salaxy.com/security/impersonation.md) |
| **Federation flow for banks** | Banks and payment providers with strong authentication create or sign in to Salaxy accounts for their users | All; production needs the Federation provider role | [Federation](https://code.salaxy.com/security/federation.md) |
| **Partner-initiated account creation** | Making sure a company account exists before onboarding — not a sign-in flow, used alongside SSO and federation | All; production needs the trusted partner role | [Account creation](https://code.salaxy.com/security/account-creation.md) |

Example code for SSO in .NET, TypeScript / JavaScript and PHP: [salaxy-demo-sso](https://gitlab.com/salaxy/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](https://code.salaxy.com/reference/rest-api.md) 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.
