> 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/authentication.md). # Authentication Obtain a JWT for use as a Bearer token on any Qvalia API ## Create access token (JWT) for accountRegNo > Exchange an API key for a short-lived JWT access token, authenticating\ > as \`accountRegNo\` (a Partner uses its own \`partnerRegNo\` here). The\ > returned token can be used as a Bearer token\ > (\`Authorization: Bearer \\`) on any Qvalia API endpoint as an\ > alternative to the API key.\ > \ > \`GET\` always authenticates as self; use \`POST\` if you need to act on\ > behalf of a child account (\`actingAs: parent\`).\ > \ > Tokens expire after one hour. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Authentication API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"Obtain a JWT for use as a Bearer token on any Qvalia API"}],"servers":[{"url":"https://api-test.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo} or POST /token (see Authentication API).\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"Account registration number issued by Qvalia. A Partner uses its own partnerRegNo here."}},"responses":{"tokenCreated":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string"},"expires_in":{"type":"integer"}}}}}}}},"paths":{"/token/{accountRegNo}":{"get":{"tags":["Authentication"],"summary":"Create access token (JWT) for accountRegNo","description":"Exchange an API key for a short-lived JWT access token, authenticating\nas `accountRegNo` (a Partner uses its own `partnerRegNo` here). The\nreturned token can be used as a Bearer token\n(`Authorization: Bearer `) on any Qvalia API endpoint as an\nalternative to the API key.\n\n`GET` always authenticates as self; use `POST` if you need to act on\nbehalf of a child account (`actingAs: parent`).\n\nTokens expire after one hour.","operationId":"authentication/get-token","parameters":[{"$ref":"#/components/parameters/accountRegNo"},{"name":"Authorization","in":"header","description":"API key for the account, sent as `Authorization: `","required":true,"schema":{"type":"string"}}],"responses":{"200":{"$ref":"#/components/responses/tokenCreated"},"401":{"description":"Unauthorized"},"422":{"description":"Unprocessable Entity"},"500":{"description":"Internal Server Error"}}}}}} ``` ## Create access token (JWT) for accountRegNo, or on behalf of a child account > Exchange an API key for a short-lived JWT access token, authenticating\ > as \`accountRegNo\` (a Partner uses its own \`partnerRegNo\` here).\ > \ > \- \`actingAs: self\` (default) — issue a token for \`accountRegNo\` itself.\ > \- \`actingAs: parent\` — a Partner issues a token to act on behalf of a\ > child account; \`forChildRegNo\` is required and the Partner must be\ > authorized for that child. The token's \`sub\` claim will be the child\ > account.\ > \ > The request body may be omitted entirely, which is equivalent to\ > \`{"actingAs": "self"}\`.\ > \ > Tokens expire after one hour. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Authentication API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"Obtain a JWT for use as a Bearer token on any Qvalia API"}],"servers":[{"url":"https://api-test.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo} or POST /token (see Authentication API).\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string","description":"","default":""},"description":"Account registration number issued by Qvalia. A Partner uses its own partnerRegNo here."}},"schemas":{"CreateTokenBody":{"type":"object","properties":{"actingAs":{"type":"string","enum":["self","parent"],"default":"self","description":"Optional, defaults to \"self\". If \"parent\", `forChildRegNo` is required and the caller must be authorized to act on behalf of that child."},"forChildRegNo":{"type":"string","description":"Required when actingAs is \"parent\"; the child account to act for."}}}},"responses":{"tokenCreated":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string"},"expires_in":{"type":"integer"}}}}}}}},"paths":{"/token/{accountRegNo}":{"post":{"tags":["Authentication"],"summary":"Create access token (JWT) for accountRegNo, or on behalf of a child account","description":"Exchange an API key for a short-lived JWT access token, authenticating\nas `accountRegNo` (a Partner uses its own `partnerRegNo` here).\n\n- `actingAs: self` (default) — issue a token for `accountRegNo` itself.\n- `actingAs: parent` — a Partner issues a token to act on behalf of a\n child account; `forChildRegNo` is required and the Partner must be\n authorized for that child. The token's `sub` claim will be the child\n account.\n\nThe request body may be omitted entirely, which is equivalent to\n`{\"actingAs\": \"self\"}`.\n\nTokens expire after one hour.","operationId":"authentication/create-token","parameters":[{"$ref":"#/components/parameters/accountRegNo"}],"requestBody":{"description":"Request body. May be omitted (defaults to `actingAs: self`).","required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTokenBody"}}}},"responses":{"200":{"$ref":"#/components/responses/tokenCreated"},"401":{"description":"Unauthorized"},"422":{"description":"Unprocessable Entity"},"500":{"description":"Internal Server Error"}}}}}} ``` ## Create access token (JWT) using client\_id/client\_secret > Exchange \`client\_id\` (your \`accountRegNo\`) and \`client\_secret\` (your API\ > key) for a short-lived JWT access token. Use this as an alternative to\ > \`POST /token/{accountRegNo}\` when you'd rather not put \`accountRegNo\` in\ > the URI and the API key in the \`Authorization\` header - for example, if\ > your client is built around an OAuth2-style client-credentials exchange.\ > \ > Supply the credentials either way:\ > \- \*\*In the body\*\* — \`client\_id\` and \`client\_secret\` as JSON fields (see below).\ > \- \*\*As HTTP Basic auth\*\* — \`Authorization: Basic base64(client\_id:client\_secret)\`,\ > per \[RFC 6749 §2.3.1]\( > the convention most off-the-shelf OAuth2 client libraries default to for a\ > client\_credentials exchange. When Basic auth is present, the body may be\ > omitted entirely (or contain only \`actingAs\`/\`forChildRegNo\`); a\ > \`client\_id\`/\`client\_secret\` pair in the body always takes precedence over\ > Basic auth if both are supplied.\ > \ > \- \`actingAs: self\` (default) — issue a token for \`client\_id\` itself.\ > \- \`actingAs: parent\` — a Partner issues a token to act on behalf of a\ > child account; \`forChildRegNo\` is required and the Partner\ > (\`client\_id\`) must be authorized for that child. The token's \`sub\`\ > claim will be the child account.\ > \ > There is no bodyless \`GET /token\` equivalent - \`GET\` always requires\ > \`accountRegNo\` in the URI, see \`GET /token/{accountRegNo}\`.\ > \ > Tokens expire after one hour. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Authentication API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"Obtain a JWT for use as a Bearer token on any Qvalia API"}],"servers":[{"url":"https://api-test.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"basic":[]},{}],"components":{"securitySchemes":{"basic":{"type":"http","scheme":"basic","description":"HTTP Basic auth as an alternative way to supply client_id/client_secret to\nPOST /token (username = client_id, password = client_secret). Only accepted\non POST /token, not on other Qvalia API endpoints.\n"}},"schemas":{"CreateTokenBody":{"type":"object","properties":{"actingAs":{"type":"string","enum":["self","parent"],"default":"self","description":"Optional, defaults to \"self\". If \"parent\", `forChildRegNo` is required and the caller must be authorized to act on behalf of that child."},"forChildRegNo":{"type":"string","description":"Required when actingAs is \"parent\"; the child account to act for."}}}},"responses":{"tokenCreated":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string"},"expires_in":{"type":"integer"}}}}}}}},"paths":{"/token":{"post":{"tags":["Authentication"],"summary":"Create access token (JWT) using client_id/client_secret","description":"Exchange `client_id` (your `accountRegNo`) and `client_secret` (your API\nkey) for a short-lived JWT access token. Use this as an alternative to\n`POST /token/{accountRegNo}` when you'd rather not put `accountRegNo` in\nthe URI and the API key in the `Authorization` header - for example, if\nyour client is built around an OAuth2-style client-credentials exchange.\n\nSupply the credentials either way:\n- **In the body** — `client_id` and `client_secret` as JSON fields (see below).\n- **As HTTP Basic auth** — `Authorization: Basic base64(client_id:client_secret)`,\n per [RFC 6749 §2.3.1](https://www.rfc-editor.org/rfc/rfc6749#section-2.3.1),\n the convention most off-the-shelf OAuth2 client libraries default to for a\n client_credentials exchange. When Basic auth is present, the body may be\n omitted entirely (or contain only `actingAs`/`forChildRegNo`); a\n `client_id`/`client_secret` pair in the body always takes precedence over\n Basic auth if both are supplied.\n\n- `actingAs: self` (default) — issue a token for `client_id` itself.\n- `actingAs: parent` — a Partner issues a token to act on behalf of a\n child account; `forChildRegNo` is required and the Partner\n (`client_id`) must be authorized for that child. The token's `sub`\n claim will be the child account.\n\nThere is no bodyless `GET /token` equivalent - `GET` always requires\n`accountRegNo` in the URI, see `GET /token/{accountRegNo}`.\n\nTokens expire after one hour.","operationId":"authentication/create-token-client-credentials","requestBody":{"description":"Request body. May be omitted (or contain only `actingAs`/`forChildRegNo`)\nwhen `client_id`/`client_secret` are instead supplied via HTTP Basic auth.","required":false,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CreateTokenBody"},{"type":"object","properties":{"client_id":{"type":"string","description":"Your accountRegNo (a Partner uses its own partnerRegNo here). Required unless supplied via HTTP Basic auth instead."},"client_secret":{"type":"string","description":"Your API key. Required unless supplied via HTTP Basic auth instead."}}}]}}}},"responses":{"200":{"$ref":"#/components/responses/tokenCreated"},"401":{"description":"Unauthorized"},"422":{"description":"Unprocessable Entity"},"500":{"description":"Internal Server Error"}}}}}} ``` --- # 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/authentication.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.