Authentication

Qonic uses OAuth 2.1 Authorization Code (with optional PKCE). You obtain an authorization code via the browser, then exchange it for a bearer token at /v1/auth/token.

Prerequisites

Create an Application in the Qonic developer portal to get a client_id and client_secret.
Whitelist one or more exact Redirect URIs for your app (e.g., http://localhost:8765/callback).
(Optional but recommended) Implement PKCE to protect the authorization code exchange.

Available scopes

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

Scope	Description
`projects:read`	View project details and membership.
`projects:write`	Create and manage projects.
`models:read`	View and download models.
`models:write`	Upload, update, and delete models.
`issues:read`	View issues and tasks.
`libraries:read`	View project material, codification, and property libraries.
`libraries:write`	Manage project material, codification, and property libraries.

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:

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 – (PKCE) base64url(SHA256(code_verifier))
code_challenge_method – S256 when using PKCE

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 client_secret and (if you used PKCE) your code_verifier.

client_id (required)
client_secret (required)
code (required)
redirect_uri (required) (must exactly match the authorize step)
code_verifier (required if you sent code_challenge)
grant_type (required) (must be equal to authorization_code)

The response contains a bearer token you can use to call the API. Store it securely and treat it like a password.

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.

Security notes

Do not embed the client_secret in browser-only/public apps.
For Single Page Applications, perform the token exchange on a backend (your server) or another trusted runtime, and return only the token to the frontend.
PKCE is recommended; supply code_challenge on authorize and code_verifier on token exchange.