Authentication

Prerequisites

1. Create an Application in the Qonic developer portal to get a client_id. Server-side apps also receive a client_secret. SPAs and native apps can be registered as public clients and have no secret.
2. Whitelist one or more exact Redirect URIs for your app (e.g., http://localhost:8765/callback).
3. Implement PKCE: generate a code_verifier and derive code_challenge = base64url(SHA256(code_verifier)). PKCE is required for all clients.

Available scopes

Request scopes as a space-separated list during the authorize step. The following scopes are supported:

Example scope string: projects:read projects:write models:read models:write

Authorization Code flow

1) Redirect the user to authorize

Build a URL to /v1/auth/authorize with the following query parameters:

• response_type – must be code
• client_id – your application's client ID
• redirect_uri – one of your whitelisted redirect URIs
• scope – space-separated scope list
• state – opaque anti-CSRF value you validate on return
• code_challenge (required) – base64url(SHA256(code_verifier))
• code_challenge_method (required) – must be S256

If the user is not signed in, the server will initiate your configured login (OpenID Connect cookie flow). If prior consent doesn’t exist, the user will see a consent page rendered by Qonic at /v1/auth/authorize, which posts to /v1/auth/consent.

2) Handle the redirect

After approval, Qonic redirects to your redirect_uri with:

• ?code=... – the authorization code
• &state=... – the value you originally passed

3) Exchange the code for a token

Exchange the code by doing a POST request to /v1/auth/token. The server validates your code_verifier and, for confidential clients, your client_secret.

• client_id (required)
• client_secret (required for server-side apps; must be omitted for SPAs and native apps)
• code (required)
• redirect_uri (required) – must exactly match the authorize step
• code_verifier (required)
• grant_type (required) – must be authorization_code

The response contains a bearer token you can use to call the API:

Store the token securely and treat it like a password.

Token lifecycle

Access tokens are persistent access tokens (PATs). Depending on your application configuration, tokens may be valid indefinitely or have an expiration date set at creation time.

• No expires_in field is returned in the token response. Check your application settings in the developer portal for the configured token lifetime.
• There is no refresh token mechanism. When a token expires or is revoked, you must re-authenticate through the full OAuth authorization code flow.
• Tokens can be revoked at any time — manage and revoke your active tokens, or withdraw an application's consent, from the Qonic developer portal. If you receive a 401 Unauthorized response for a previously valid token, re-authenticate to obtain a new one.

Using the bearer token

Add the token to the Authorization header:

Full working example (Python)

This script opens a browser, runs a tiny local HTTP callback server, and exchanges the code at /v1/auth/token. It matches the server flow described above.

Handling authentication errors

If a request is made with an invalid or expired token, the API returns a 401 Unauthorized response:

If your token has insufficient scopes for the requested resource, the API returns a 403 Forbidden response. Verify that your token includes the required scopes listed in the scopes table.

Security notes

• PKCE is required for all clients. Only the S256 challenge method is accepted. The code_verifier must always be sent on the token exchange.
• Tokens must be sent in the Authorization: Bearer header. Query-string token transport (?access_token=) is not supported.
• For SPAs and native apps, register a public client in the developer portal. Public clients have no client_secret — PKCE is the sole binding mechanism. Do not supply a client_secret on the token exchange.
• For server-side apps, keep your client_secret on the server and never expose it to the browser.