Authentication

The KLIQ AI API supports three authentication methods: API keys, JWT tokens, and OAuth2 client credentials.

API Key Authentication

The simplest way to authenticate. Include your API key in the X-API-Key header with every request.

import { KliqClient } from '@kliq-ai/sdk';

const kliq = new KliqClient({
apiKey: process.env.KLIQ_API_KEY!,
});

Keep your API key secret

Never expose your API key in client-side code or public repositories. Use environment variables and server-side requests.

Raw HTTP Example

GET /v1/tenants/t_abc123/observations HTTP/1.1
Host: api.kliq-ai.eu
X-API-Key: kliq_sk_abc123...

JWT Token Authentication

For user-scoped actions, use JWT tokens obtained via the token endpoint.

POST/v1/auth/tokenExchange credentials for a JWT token

POST/v1/auth/refreshRefresh an expired JWT token

// Exchange credentials for a token
const { accessToken, refreshToken } = await kliq.auth.getToken({
email: 'user@example.com',
password: 'your-password',
});

// Use the token for subsequent requests
const kliqAuth = new KliqClient({
accessToken,
});

// Refresh when expired
const newTokens = await kliq.auth.refresh(refreshToken);

OAuth2 Client Credentials

For service-to-service integration, use the OAuth2 client credentials flow.

OAuth2 client credentials is the recommended flow for service-to-service authentication. The SDK handles token acquisition and refresh automatically.

const kliq = new KliqClient({
clientId: process.env.KLIQ_CLIENT_ID!,
clientSecret: process.env.KLIQ_CLIENT_SECRET!,
});

// The SDK handles token acquisition and refresh automatically

Scopes and Permissions

Authorization is role-based today. Your membership role in a tenant determines your access level:

Role	Description
`viewer`	Read-only access to observations and CV results
`member`	Full access to observations and CV jobs
`manager`	Team management and webhook configuration
`admin`	Full tenant administration
`owner`	Complete control including billing and members

Per-key scope enforcement is on the roadmap. Today, authorization is controlled by your tenant membership role. Fine-grained API key scopes will be available in a future release.

AuthConfig

Property	Type	Required	Description
apiKey	string	No	API key for simple authentication
accessToken	string	No	JWT access token
clientId	string	No	OAuth2 client ID
clientSecret	string	No	OAuth2 client secret
baseUrl	string	No	API base URL (defaults to production)

Error Codes

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

Next steps

Getting Started — Quick start guide
Webhooks — Set up event notifications
API Reference — Full endpoint documentation