Auth API (OIDC)

The public integrator surface of auth.codai.ro: discovery, authorization code + PKCE, device flow, tokens, logout and /connect/key.

auth.codai.ro is a standard OpenID Provider; read /.well-known/openid-configuration first and let your OIDC library drive the rest. The one codai-specific endpoint is GET /connect/key: exchange the access token for a scoped inference key (base_url: https://ai.codai.ro/v1). Only the endpoints an integrator calls are listed — the login/consent UI, account API and native app routes are first-party internals. OIDC errors are { "error", "error_description" }. Flow walkthrough: connect flow, scopes: scopes.

Response Body

`application/json`

curl -X GET "https://example.com/.well-known/openid-configuration"

{  "issuer": "https://auth.codai.ro",  "authorization_endpoint": "http://example.com",  "token_endpoint": "http://example.com",  "userinfo_endpoint": "http://example.com",  "jwks_uri": "http://example.com",  "introspection_endpoint": "http://example.com",  "revocation_endpoint": "http://example.com",  "device_authorization_endpoint": "http://example.com",  "end_session_endpoint": "http://example.com",  "registration_endpoint": "http://example.com",  "response_types_supported": [    "string"  ],  "grant_types_supported": [    "string"  ],  "token_endpoint_auth_methods_supported": [    "string"  ],  "scopes_supported": [    "string"  ],  "claims_supported": [    "string"  ],  "code_challenge_methods_supported": [    "S256"  ],  "acr_values_supported": [    "string"  ],  "subject_types_supported": [    "string"  ],  "id_token_signing_alg_values_supported": [    "string"  ],  "backchannel_logout_supported": true}

Response Body

`application/json`

curl -X GET "https://example.com/jwks"

{  "keys": [    {      "kty": "RSA",      "kid": "string",      "use": "sig",      "alg": "RS256",      "n": "string",      "e": "string"    }  ]}

Query Parameters

response_type*"code"

Must be code.

Value in

"code"

client_id*string

Registered client identifier.

redirect_uri*string

One of the client's registered redirect URIs (exact match).

Formaturi

scope*string

Space-separated scopes; must include openid.

state?string

Opaque CSRF value echoed back on the redirect. Strongly recommended.

code_challenge*string

BASE64URL(SHA-256(code_verifier)) — PKCE is required for every client.

code_challenge_method*"S256"

Only S256 is supported.

Value in

"S256"

nonce?string

Replay protection echoed into the ID token.

prompt?string

Standard OIDC prompt values (login, consent, none, select_account).

acr_values?string

Requested authentication context; passkey/mfa trigger step-up.

resource?string

RFC 8707 resource indicator. https://ai.codai.ro/mcp yields a JWT access token with the mcp scope.

Formaturi

mode?"signup"

codai extension — signup opens the sign-up form directly.

Value in

"signup"

ref?string

codai extension — referral code (codai.ro/r/<username>, 3–20 chars [A-Za-z0-9_]) pre-filled on sign-up.

Match^[A-Za-z0-9_]{3,20}$

lang?string

UI language of the login pages. Defaults from the NEXT_LOCALE cookie, then Accept-Language.

Value in

"ro"
"en"

Response Body

`text/html`

curl -X GET "https://example.com/auth?response_type=code&client_id=metu&redirect_uri=http%3A%2F%2Fexample.com&scope=openid+email+profile+inference+keys%3Amanage&code_challenge=string&code_challenge_method=S256"

Empty

Request Body

application/x-www-form-urlencoded

TypeScript Definitions

Use the request body type in TypeScript.

client_id*string

scope?string

Space-separated scopes.

resource?string

Optional RFC 8707 resource indicator.

Formaturi

Response Body

`application/json`

curl -X POST "https://example.com/device/auth" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'client_id=codai-cli'

{  "device_code": "string",  "user_code": "BCDF-GHJK",  "verification_uri": "https://auth.codai.ro/device",  "verification_uri_complete": "http://example.com",  "expires_in": 0,  "interval": 5}

Authorization

clientSecretBasic

AuthorizationBasic <token>

client_secret_basic client authentication. client_secret_post and private_key_jwt go in the form body instead; public clients send only client_id.

In: header

Request Body

application/x-www-form-urlencoded

TypeScript Definitions

Use the request body type in TypeScript.

Form-encoded body. Fields depend on grant_type; client credentials depend on the client's authentication method.

grant_type*string

Value in

"authorization_code"
"refresh_token"
"urn:ietf:params:oauth:grant-type:device_code"

code?string

authorization_code — the code from the redirect.

redirect_uri?string

authorization_code — must equal the value used at /auth.

Formaturi

code_verifier?string

authorization_code — PKCE verifier (43–128 chars) whose S256 hash was sent as code_challenge.

refresh_token?string

refresh_token grant.

device_code?string

device_code grant — from /device/auth.

scope?string

Optional down-scoping on refresh.

resource?string

RFC 8707 resource indicator.

Formaturi

client_id?string

Public clients (none) and client_secret_post.

client_secret?string

client_secret_post only.

client_assertion_type?string

private_key_jwt only.

client_assertion?string

private_key_jwt — JWT signed with a key from the client's registered jwks / jwks_uri.

Response Body

`application/json`

curl -X POST "https://example.com/token" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'grant_type=authorization_code'

{  "access_token": "string",  "token_type": "Bearer",  "expires_in": 3600,  "scope": "string",  "id_token": "string",  "refresh_token": "string"}

Authorization

clientSecretBasic

AuthorizationBasic <token>

client_secret_basic client authentication. client_secret_post and private_key_jwt go in the form body instead; public clients send only client_id.

In: header

Request Body

application/x-www-form-urlencoded

TypeScript Definitions

Use the request body type in TypeScript.

token*string

token_type_hint?string

Value in

"access_token"
"refresh_token"

client_id?string

For client_secret_post / none.

client_secret?string

For client_secret_post.

client_assertion_type?string

For private_key_jwt.

client_assertion?string

Response Body

`application/json`

curl -X POST "https://example.com/token/introspection" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'token=string'

{  "active": true,  "scope": "string",  "client_id": "string",  "sub": "string",  "token_type": "string",  "exp": 0,  "iat": 0,  "iss": "http://example.com",  "aud": "string",  "jti": "string"}

Authorization

clientSecretBasic

AuthorizationBasic <token>

client_secret_basic client authentication. client_secret_post and private_key_jwt go in the form body instead; public clients send only client_id.

In: header

Request Body

application/x-www-form-urlencoded

TypeScript Definitions

Use the request body type in TypeScript.

token*string

token_type_hint?string

Value in

"access_token"
"refresh_token"

client_id?string

client_secret?string

client_assertion_type?string

client_assertion?string

Response Body

`application/json`

curl -X POST "https://example.com/token/revocation" \  -H "Content-Type: application/x-www-form-urlencoded" \  -d 'token=string'

Empty

Authorization

bearerAuth

AuthorizationBearer <token>

OAuth access token issued by /token (used by /me and /connect/key).

In: header

Response Body

`application/json`

curl -X GET "https://example.com/me"

{  "sub": "string",  "email": "[email protected]",  "email_verified": true,  "name": "string",  "picture": "http://example.com"}

Query Parameters

id_token_hint?string

The ID token previously issued to this client; identifies the session and client.

post_logout_redirect_uri?string

Registered post-logout redirect URI of the client.

Formaturi

state?string

Opaque value appended to the post-logout redirect.

client_id?string

Required when id_token_hint is absent and a post_logout_redirect_uri is given.

ui_locales?string

Standard OIDC parameter; the codai UI reads ?lang=ro|en instead.

Response Body

`text/html`

curl -X GET "https://example.com/session/end"

"string"

Authorization

bearerAuth

AuthorizationBearer <token>

OAuth access token issued by /token (used by /me and /connect/key).

In: header

Header Parameters

X-Codai-Device-Name?string

First-party clients only — label (≤ 60 chars) for the per-device key; defaults to Desktop.

Lengthlength <= 60

Response Body

`application/json`

curl -X GET "https://example.com/connect/key"

{  "api_key": "codai_xxxxxxxxxxxxxxxxxxxxxxxx",  "api_key_id": "b0dd218e-3bcf-4bdb-a1e3-0689d60a8afd",  "base_url": "https://ai.codai.ro/v1",  "model": "codai",  "already_issued": true}

Header Parameters

Origin?string

Formaturi

Response Body

`application/json`

curl -X OPTIONS "https://example.com/connect/key"

Empty

Response Body

`application/json`

curl -X GET "https://example.com/health"

{  "ok": true}

Response Body

`application/json`

curl -X GET "https://example.com/health/ready"

{  "ok": true,  "checks": {    "db": {      "ok": true,      "error": "string"    }  }}

200application/json

200application/json

303

400text/html

200application/json

400application/json

401application/json

200application/json

400application/json

401application/json

429application/json

200application/json

400application/json

401application/json

200

400application/json

401application/json

200application/json

401application/json

200text/html

303

400text/html

200application/json

400application/json

401application/json

403application/json

204

403application/json

200application/json

200application/json

503application/json

`application/json`

`application/json`

`text/html`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`text/html`

`text/html`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`