Ways to authenticate

Every Qvalia Public API endpoint accepts either:

• an API key, sent as the Authorization header, or

• a short-lived JWT access token, sent as Authorization: Bearer <token>.

API key access

Every Qvalia account has an API key, which is a long-lived secret that can be used to authenticate as that account.

The API key is sent in the Authorization header as: Authorization: <api_key>

The API key is issued by Qvalia and can be rotated or revoked using Qvalia's portal, or through Qvalia Helpdesk. You'll find your API key in the Qvalia portal under API & SFTP settings.

If you are a Partner, your API key is issued to your Partner account, and you will use your own partnerRegNo as the accountRegNo when authenticating.

It is the responsibility of the account holder to keep the API key secret!

API Keys can not be fetch again after they have been issued, so make sure to store it securely. If you lose your API key, you can generate a new one in the Qvalia portal.

JWT access token through the /token endpoint

Use /token to exchange your credentials for a JWT. There are three ways to do this, depending on your role and who you want to authenticate as:

1. Authenticate as yourself (accountRegNo in the URI). Call GET or POST /token/{accountRegNo} with your own accountRegNo in the URI and your API key in the Authorization header. This also applies if you are a Partner: a Partner always authenticates using its own partnerRegNo as the accountRegNo — never a child account's regNo. Access to a specific child account (e.g. via /partner/{partnerRegNo}/... endpoints) is granted on the Partner's child account.

2. Partner acting on behalf of a child account (actingAs: parent) — a Partner can request a token scoped to one of its child accounts by POST'ing to /token/{partnerRegNo} (or /token, see below) with actingAs: parent and forChildRegNo: <childAccountRegNo> in the body. The Partner must be authorized to act on behalf of that child. The resulting token's sub claim is the child account, so it can be used to call endpoints that operate directly on the child account (e.g. SCIM user provisioning) on the child's behalf, meaning that /partner/{partnerRegNo} can be omitted from the URI when calling a child's account, e.g. /transaction/{accountRegNo}.

3. Client credentials (no accountRegNo in the URI) — instead of putting accountRegNo in the URI and the API key in the Authorization header, you may POST to /token with client_id (your accountRegNo) and client_secret (your API key) in the body. This is functionally equivalent to option 1 (or option 2, if combined with actingAs: parent), and is useful for clients that model authentication as an OAuth2-style client-credentials exchange.

Tokens expire after one hour.