Authentication

All API requests to Qarion require authentication. The platform supports two authentication methods — API keys for server-to-server integrations and session tokens for browser-based applications — each suited to different use cases.

API Keys

API keys are the recommended method for programmatic access, CI/CD pipelines, and any server-side integration. They provide persistent credentials that don't expire on their own, making them ideal for automated workflows that run unattended.

Creating an API Key

To create an API key, log in to Qarion and navigate to Settings → API Keys. Click Generate New Key, and the platform will display the key once. Copy and securely store the key at this point — for security reasons, the full key cannot be retrieved after this initial display. If you lose a key, you'll need to generate a new one and revoke the old one.

Using API Keys

Include the key in the Authorization header of every request, using the Bearer scheme:

curl -X GET "https://api.qarion.com/catalog/spaces/my-space/products" \
  -H "Authorization: Bearer YOUR_API_KEY"

Key Permissions

API keys inherit the permissions of the user who created them. This means the key can only access spaces that the creating user belongs to, and actions are constrained by that user's role (Admin, Editor, or Viewer) within each space. If you need a key with broad access, create it from a service account that has the appropriate membership and roles.

Key Management

The following endpoints let you manage your API keys programmatically:

Endpoint	Method	Description
GET /api-keys	GET	List your API keys
POST /api-keys	POST	Create a new key
DELETE /api-keys/{id}	DELETE	Revoke a key

Session Tokens

Session tokens are designed for browser-based applications where a user authenticates interactively. They are short-lived and tied to a specific user session, making them appropriate for frontend applications and interactive tools.

Login Flow

To obtain a session token, send the user's credentials to the login endpoint. The response includes an access token that you can use for subsequent API requests:

# 1. Authenticate
curl -X POST "https://api.qarion.com/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'

# Response: { "access_token": "eyJ...", "token_type": "bearer" }

Token Usage

Use the token in the same way as an API key — by including it in the Authorization header:

# 2. Use the token
curl -X GET "https://api.qarion.com/users/me" \
  -H "Authorization: Bearer eyJ..."

Token Expiration

Session tokens expire based on your organization's security policy. When a token expires, the API returns a 401 Unauthorized response. At that point, your application should re-authenticate by calling the login endpoint again. For long-running browser sessions, consider implementing a token refresh mechanism that re-authenticates silently in the background.

Security Best Practices

Protecting your API credentials is essential for maintaining the security of your data catalog. Never expose API keys in client-side code — keys embedded in JavaScript bundles or HTML pages can be easily extracted by anyone who views the page. Instead, store keys in environment variables or a secrets manager, and proxy API calls through your backend server.

Rotate your API keys regularly — a monthly cadence is a reasonable starting point for most organizations. If a key is compromised, revoke it immediately and generate a replacement. For service accounts, follow the principle of least privilege by assigning only the roles and space memberships that the integration actually needs. Finally, monitor API key usage in the admin dashboard to detect any unexpected patterns that might indicate unauthorized access.

Error Responses

When authentication fails, the API returns one of two status codes:

Status	Meaning
401 Unauthorized	Missing or invalid token
403 Forbidden	Valid token but insufficient permissions

A 401 response means the request either didn't include an Authorization header or the provided token is invalid or expired. A 403 response means the token is valid, but the authenticated user doesn't have permission to perform the requested action — for example, trying to create a product in a space where the user only has Viewer access.

{
  "detail": "Could not validate credentials"
}