API-ul Auth (OIDC)

Suprafața publică pentru integratori a auth.codai.ro: discovery, authorization code + PKCE, device flow, tokenuri, logout și /connect/key.

auth.codai.ro e un OpenID Provider standard; citește mai întâi /.well-known/openid-configuration și lasă biblioteca ta OIDC să conducă restul. Singurul endpoint specific codai e GET /connect/key: schimbi access token-ul pe o cheie de inferență cu scope-uri (base_url: https://ai.codai.ro/v1). Sunt listate doar endpoint-urile pe care le apelează un integrator — UI-ul de login/consimțământ, API-ul de cont și rutele aplicației native sunt interne first-party. Erorile OIDC sunt { "error", "error_description" }. Fluxul pas cu pas: fluxul connect, scope-uri: scope-uri.

Corpul răspunsului

`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}

Corpul răspunsului

`application/json`

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

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

Parametri query

response_type*"code"

Trebuie să fie code.

Valoare în

"code"

client_id*string

Identificatorul clientului înregistrat.

redirect_uri*string

Unul dintre redirect URI-urile înregistrate ale clientului (potrivire exactă).

Formaturi

scope*string

Scope-uri separate prin spațiu; trebuie să includă openid.

state?string

Valoare CSRF opacă, întoarsă la redirect. Puternic recomandată.

code_challenge*string

BASE64URL(SHA-256(code_verifier)) — PKCE este obligatoriu pentru fiecare client.

code_challenge_method*"S256"

Doar S256 este suportat.

Valoare în

"S256"

nonce?string

Protecție anti-replay, copiată în ID token.

prompt?string

Valorile standard OIDC pentru prompt (login, consent, none, select_account).

acr_values?string

Contextul de autentificare cerut; passkey/mfa declanșează step-up.

resource?string

Indicator de resursă RFC 8707. https://ai.codai.ro/mcp produce un access token JWT cu scope-ul mcp.

Formaturi

mode?"signup"

Extensie codai — signup deschide direct formularul de înregistrare.

Valoare în

"signup"

ref?string

Extensie codai — cod de recomandare (codai.ro/r/<username>, 3–20 caractere [A-Za-z0-9_]) precompletat la înregistrare.

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

lang?string

Limba paginilor de login. Implicit din cookie-ul NEXT_LOCALE, apoi din Accept-Language.

Valoare în

"ro"
"en"

Corpul răspunsului

`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"

Gol

Corpul cererii

application/x-www-form-urlencoded

Definiții TypeScript

Folosește tipul request body în TypeScript.

client_id*string

scope?string

Scope-uri separate prin spațiu.

resource?string

Indicator de resursă RFC 8707, opțional.

Formaturi

Corpul răspunsului

`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}

Autorizare

clientSecretBasic

AutorizareBasic <token>

Autentificare client client_secret_basic. client_secret_post și private_key_jwt merg în body-ul formularului; clienții publici trimit doar client_id.

În: header

Corpul cererii

application/x-www-form-urlencoded

Definiții TypeScript

Folosește tipul request body în TypeScript.

Body form-encoded. Câmpurile depind de grant_type; credențialele clientului depind de metoda lui de autentificare.

grant_type*string

Valoare în

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

code?string

authorization_code — codul primit la redirect.

redirect_uri?string

authorization_code — trebuie să fie egal cu valoarea folosită la /auth.

Formaturi

code_verifier?string

authorization_code — verificatorul PKCE (43–128 caractere) al cărui hash S256 a fost trimis ca code_challenge.

refresh_token?string

Grant-ul refresh_token.

device_code?string

Grant-ul device_code — de la /device/auth.

scope?string

Restrângere opțională a scope-urilor la refresh.

resource?string

Indicator de resursă RFC 8707.

Formaturi

client_id?string

Clienți publici (none) și client_secret_post.

client_secret?string

Doar client_secret_post.

client_assertion_type?string

Doar private_key_jwt.

client_assertion?string

private_key_jwt — JWT semnat cu o cheie din jwks / jwks_uri înregistrate ale clientului.

Corpul răspunsului

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

Autorizare

clientSecretBasic

AutorizareBasic <token>

Autentificare client client_secret_basic. client_secret_post și private_key_jwt merg în body-ul formularului; clienții publici trimit doar client_id.

În: header

Corpul cererii

application/x-www-form-urlencoded

Definiții TypeScript

Folosește tipul request body în TypeScript.

token*string

token_type_hint?string

Valoare în

"access_token"
"refresh_token"

client_id?string

Pentru client_secret_post / none.

client_secret?string

Pentru client_secret_post.

client_assertion_type?string

Pentru private_key_jwt.

client_assertion?string

Corpul răspunsului

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

Autorizare

clientSecretBasic

AutorizareBasic <token>

Autentificare client client_secret_basic. client_secret_post și private_key_jwt merg în body-ul formularului; clienții publici trimit doar client_id.

În: header

Corpul cererii

application/x-www-form-urlencoded

Definiții TypeScript

Folosește tipul request body în TypeScript.

token*string

token_type_hint?string

Valoare în

"access_token"
"refresh_token"

client_id?string

client_secret?string

client_assertion_type?string

client_assertion?string

Corpul răspunsului

`application/json`

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

Gol

Autorizare

bearerAuth

AutorizareBearer <token>

Access token OAuth emis de /token (folosit de /me și /connect/key).

În: header

Corpul răspunsului

`application/json`

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

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

Parametri query

id_token_hint?string

ID token-ul emis anterior acestui client; identifică sesiunea și clientul.

post_logout_redirect_uri?string

URI-ul de redirect post-logout înregistrat al clientului.

Formaturi

state?string

Valoare opacă adăugată la redirect-ul post-logout.

client_id?string

Obligatoriu când lipsește id_token_hint și se dă un post_logout_redirect_uri.

ui_locales?string

Parametru standard OIDC; interfața codai citește în schimb ?lang=ro|en.

Corpul răspunsului

`text/html`

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

"string"

Autorizare

bearerAuth

AutorizareBearer <token>

Access token OAuth emis de /token (folosit de /me și /connect/key).

În: header

Parametri header

X-Codai-Device-Name?string

Doar clienți first-party — eticheta (≤ 60 caractere) a cheii per dispozitiv; implicit Desktop.

Lungimelength <= 60

Corpul răspunsului

`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}

Parametri header

Origin?string

Formaturi

Corpul răspunsului

`application/json`

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

Gol

Corpul răspunsului

`application/json`

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

{  "ok": true}

Corpul răspunsului

`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`