All requests to the Qpien API must be authenticated using an access token.
This page explains how to generate and use tokens, as well as important notes about token lifecycle.
How It Works#
1.
Each customer can generate one or more API Keys in the Qpien App dashboard.An API Key contains a Client ID and Client Secret.
Each API Key also has a set of scopes (permissions) such as read and write.
2.
To interact with the API, you must first call the GraphQL mutation generateOAuthToken with your Client ID and Client Secret.
3.
You will receive an access token that is valid for 1 hour.Include this token in the Authorization header of every request:Authorization: Bearer <access_token>
4.
If you update the scopes of your API key in the dashboard (e.g., enabling write), you must generate a new access token.Old tokens will not automatically gain new permissions.
5.
When your token got expired, simply call generateOAuthToken again with the same Client ID and Client Secret to get a fresh token.
Get Access Token#
GraphQL Mutation#
Example in Bash (cURL)#
Example in Node.js#
Using the Token#
After retrieving your token, include it in the Authorization header of every request:Error Handling#
If something goes wrong while authenticating, the API will return one of the following error codes:| Error Code | Description |
|---|
UNAUTHORIZED | Missing or invalid token. |
INVALID_CLIENT | The provided Client ID or Client Secret is incorrect. |
TOKEN_EXPIRED | The token has expired (tokens last for 1 hour). Generate a new one. |
INSUFFICIENT_SCOPES | Your token does not have permission for this operation. Update scopes and generate a new token. |
Best Practices#
📌 Always store your Client Secret securely. Never expose it in frontend code.📌 Regenerate your token when it expires by calling generateOAuthToken again.📌 Generate a new token after updating your API key’s scopes.📌 For long-running jobs, implement retry logic to handle TOKEN_EXPIRED gracefully. Modified at 2025-11-28 08:54:09
