> For the complete documentation index, see [llms.txt](https://api.qvalia.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.qvalia.io/api-documentation/apis/ways-to-authenticate.md). # 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 `. #### 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: ```http Authorization: ``` 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: ` 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) either in the body, or as HTTP Basic auth (`Authorization: Basic base64(client_id:client_secret)` — the convention most OAuth2 client libraries default to). 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://api.qvalia.io/api-documentation/apis/ways-to-authenticate.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.