Documents
Authentication Introduction
Latest Update Time: 2026-07-02 00:00:00
Authentication is the first step to using QIMA Public APIs — every endpoint is protected and requires a valid access token. This module provides APIs for getting, refreshing, and revoking that token.
This page documents the shared setup used by every Authentication guide. Each API-specific guide links back here for authentication, headers, and environment details.
Base URL
All Authentication APIs are served from the QIMA Public API host for your environment:
https://ppapi.qima.com
For production integrations, replace the host with the QIMA API host provided for your environment.
Required Headers
You need a QIMA customer account and an Ai-Api-Access-Token for the target environment, provided by QIMA. The Get Token API (see the Getting Started Guide) only needs Ai-Api-Access-Token and Referer, since you don't have a user session yet. Refresh Token and Revoke Token need the full set below, since they act on an existing session.
| Header / Parameter | Location | Source | Description |
|---|---|---|---|
Ai-Api-Access-Token | Request header (all Authentication APIs) | Provided by QIMA | Request source identifier. Each client may have a different value per environment. |
Authorization | Request header (Refresh Token, Revoke Token) | Get Token API response content.token.token | Format: Bearer <access-token>. The access token to refresh or revoke. |
Referer | Request header (all Authentication APIs) | Fixed value | https://preprodmy.qima.com/ |
Ai-Api-Refresh-Key | Request header (Refresh Token, Revoke Token) | Get Token / Refresh Token API response content.refreshKey | The refresh key associated with the token being refreshed or revoked. |
Common Authentication Errors
These errors apply across Authentication APIs:
| Status | Meaning | Recommended Action |
|---|---|---|
401 Unauthorized | Credentials, token, or refresh key are invalid or don't match. | Re-check the account/password (Get Token) or Authorization/Ai-Api-Refresh-Key (Refresh/Revoke Token). |
403 Forbidden | Ai-Api-Access-Token is missing, invalid, or not valid for the requested user type. | Confirm the token was issued for the correct environment and user type. |
Each API guide includes additional operation-specific error codes.
Available APIs
| API | Method | Endpoint | Guide | API Reference |
|---|---|---|---|---|
| Get token | POST | /auth/v2/token | Getting Started Guide | API Reference |
| Refresh token | PUT | /auth/v2/token | Refresh Token Guide | API Reference |
| Revoke token | DELETE | /auth/v2/token | Revoke Token Guide | API Reference |
Integration Workflow
| Step | Guide |
|---|---|
| Get token | Getting Started Guide |
| Refresh token before it expires | Refresh Token Guide |
| Revoke token when done | Revoke Token Guide |
validBefore in the Get Token / Refresh Token response is a Unix timestamp (seconds) — refresh the token before this time to avoid 401/403 errors on subsequent calls.
Choosing the Right API
| Your goal | Recommended APIs |
|---|---|
| Authenticate for the first time | Get Token |
| Extend a session without asking the user to log in again | Refresh Token |
| Log out / invalidate a token immediately | Revoke Token |
Related Documentation
- Getting Started Guide — Authentication and first API call
- Module Overview — Overview of all QIMA Public API modules
- API Reference — Interactive endpoint explorer for all Public APIs