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.

GET

/.well-known/openid-configuration

Response Body

Provider metadata.

application/json

response

Subset of the discovery document that integrators rely on; the live document contains more keys.

issuer*string

Formaturi

authorization_endpoint*string

Formaturi

token_endpoint*string

Formaturi

userinfo_endpoint?string

Formaturi

jwks_uri*string

Formaturi

introspection_endpoint?string

Formaturi

revocation_endpoint?string

Formaturi

device_authorization_endpoint?string

Formaturi

end_session_endpoint?string

Formaturi

registration_endpoint?string

Dynamic client registration for public MCP clients (not documented here).

Formaturi

response_types_supported*array<string>

grant_types_supported?array<string>

token_endpoint_auth_methods_supported?array<string>

scopes_supported?array<string>

claims_supported?array<string>

code_challenge_methods_supported?array<string>

acr_values_supported?array<string>

subject_types_supported*array<string>

id_token_signing_alg_values_supported*array<string>

backchannel_logout_supported?boolean

Example Request

curl -X GET 'https://auth.codai.ro/.well-known/openid-configuration'

Example Request

curl -X GET 'https://auth.codai.ro/.well-known/openid-configuration'

Example ResponseSchema200

{
  "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
}

{  "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}

GET

/jwks

Response Body

JSON Web Key Set.

application/json

response

keys*array<>

Example Request

curl -X GET 'https://auth.codai.ro/jwks'

Example Request

curl -X GET 'https://auth.codai.ro/jwks'

Example ResponseSchema200

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

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

GET

/auth

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

Redirect to the codai login/consent UI, or back to redirect_uri with code+state (or error).

Example Request

curl -X GET 'https://auth.codai.ro/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'

Example Request

curl -X GET 'https://auth.codai.ro/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'

Example Response

Empty

POST

/device/auth

Request Body

application/x-www-form-urlencoded

body

client_id*string

scope?string

Space-separated scopes.

resource?string

Optional RFC 8707 resource indicator.

Formaturi

Response Body

Device authorization issued.

application/json

response

device_code*string

user_code*string

Shown to the user; format ****-****.

verification_uri*string

Formaturi

verification_uri_complete*string

verification_uri with the user_code pre-filled.

Formaturi

expires_in*integer

Seconds until the device code expires.

interval?integer

Minimum seconds between /token polls.

Example Request

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

Example Request

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

Example ResponseSchema

{
  "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
}

{  "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}

POST

/token

Authorization

clientSecretBasic

headerAuthorizationBasic <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.

Request Body

application/x-www-form-urlencoded

body

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

Tokens issued.

application/json

response

access_token*string

Opaque (1 h), or an RS256 JWT when resource=https://ai.codai.ro/mcp.

token_type*string

expires_in*integer

scope?string

Granted scopes, space-separated.

id_token?string

Present when openid was granted. Includes sub, role, sid, auth_time, acr, amr, nonce.

refresh_token?string

Only when the client allows refresh_token and offline_access was granted. Rotated on every refresh for public clients.

Example Request

curl -X POST 'https://auth.codai.ro/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code'

Example Request

curl -X POST 'https://auth.codai.ro/token' \  -H 'Content-Type: application/x-www-form-urlencoded' \  -d 'grant_type=authorization_code'

Example ResponseSchema

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

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

POST

/token/introspection

Authorization

clientSecretBasic

headerAuthorizationBasic <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.

Request Body

application/x-www-form-urlencoded

body

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

Introspection result (also for inactive tokens).

application/json

response

active*boolean

scope?string

client_id?string

sub?string

User id (UUID).

token_type?string

exp?integer

iat?integer

iss?string

Formaturi

aud?string

Resource indicator the token was minted for.

jti?string

Example Request

curl -X POST 'https://auth.codai.ro/token/introspection' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=string'

Example Request

curl -X POST 'https://auth.codai.ro/token/introspection' \  -H 'Content-Type: application/x-www-form-urlencoded' \  -d 'token=string'

Example ResponseSchema

{
  "active": true,
  "scope": "string",
  "client_id": "string",
  "sub": "string",
  "token_type": "string",
  "exp": 0,
  "iat": 0,
  "iss": "http://example.com",
  "aud": "string",
  "jti": "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"}

POST

/token/revocation

Authorization

clientSecretBasic

headerAuthorizationBasic <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.

Request Body

application/x-www-form-urlencoded

body

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

Token revoked (or already invalid). Empty body.

Example Request

curl -X POST 'https://auth.codai.ro/token/revocation' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'token=string'

Example Request

curl -X POST 'https://auth.codai.ro/token/revocation' \  -H 'Content-Type: application/x-www-form-urlencoded' \  -d 'token=string'

Example Response

Empty

GET

/me

Authorization

bearerAuth

headerAuthorizationBearer <token>

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

Response Body

Claims for the token's subject.

application/json

response

sub*string

codai user id (UUID).

email?string

Formatemail

email_verified?boolean

name?string

picture?string

Formaturi

Example Request

curl -X GET 'https://auth.codai.ro/me'

Example Request

curl -X GET 'https://auth.codai.ro/me'

Example ResponseSchema

{
  "sub": "string",
  "email": "user@example.com",
  "email_verified": true,
  "name": "string",
  "picture": "http://example.com"
}

{  "sub": "string",  "email": "user@example.com",  "email_verified": true,  "name": "string",  "picture": "http://example.com"}

GET

/session/end

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

Logout confirmation page (or "signed out" page).

response?stringtext/html

Example Request

curl -X GET 'https://auth.codai.ro/session/end'

Example Request

curl -X GET 'https://auth.codai.ro/session/end'

Example ResponseSchema

"string"

"string"

GET

/connect/key

Authorization

bearerAuth

headerAuthorizationBearer <token>

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

Header Parameters

Response Body

Key minted (first call) or already issued.

application/json

response

api_key*|

Plaintext key, returned only once per grant (null afterwards). Store it sealed.

api_key_id*string

Stable id of the minted key (revocable from the console).

Formatuuid

base_url*string

OpenAI-compatible base URL to use the key against.

Formaturi

model*string

already_issued*boolean

true when the plaintext was already handed out on an earlier call.

Example Request

curl -X GET 'https://auth.codai.ro/connect/key'

Example Request

curl -X GET 'https://auth.codai.ro/connect/key'

Example ResponseSchema

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

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

OPTIONS

/connect/key

Header Parameters

Response Body

Preflight accepted.

Example Request

curl -X OPTIONS 'https://auth.codai.ro/connect/key'

Example Request

curl -X OPTIONS 'https://auth.codai.ro/connect/key'

Example Response

Empty

GET

/health

Response Body

Process is up.

application/json

response

ok*boolean

Example Request

curl -X GET 'https://auth.codai.ro/health'

Example Request

curl -X GET 'https://auth.codai.ro/health'

Example ResponseSchema200

{
  "ok": true
}

{  "ok": true}

GET

/health/ready

Response Body

Database reachable.

application/json

response

ok*boolean

checks*

Example Request

curl -X GET 'https://auth.codai.ro/health/ready'

Example Request

curl -X GET 'https://auth.codai.ro/health/ready'

Example ResponseSchema

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

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

Auth API (OIDC)

Response BodyCopy Anchor Link

Response BodyCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Response BodyCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Response BodyCopy Anchor Link

Response BodyCopy Anchor Link

Response Body

Response Body

Query Parameters

Response Body

Request Body

Response Body

Authorization

Request Body

Response Body

Authorization

Request Body

Response Body

Authorization

Request Body

Response Body

Authorization

Response Body

Query Parameters

Response Body

Authorization

Header Parameters

Response Body

Header Parameters

Response Body

Response Body

Response Body