codai Tokens API
Token issuance, introspection (RFC 7662) and revocation (RFC 7009).
Token issuance, introspection (RFC 7662) and revocation (RFC 7009).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/codai-ro:codai-ro-tokens-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Codai Ro Tokens API
version: '1'
description: 'Operations tagged Tokens across 2 of this provider''s published API definitions: codai-ro-auth-openapi.json, codai-ro-auth-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://auth.codai.ro
description: Production
security: []
tags:
- name: Tokens
description: Token issuance, introspection (RFC 7662) and revocation (RFC 7009).
paths:
/token:
post:
operationId: token
tags:
- Tokens
summary: Token endpoint
description: 'Exchanges an authorization code (with `code_verifier`), a refresh token, or an approved
device code for tokens. Authenticate the client with HTTP Basic (`client_secret_basic`),
body credentials (`client_secret_post`), a `client_assertion` (`private_key_jwt`), or
just `client_id` for public clients (`none`). Public clients receive a **rotated**
refresh token on every refresh — always store the newest one. Throttled to 60 requests
per minute per IP. Browser calls from `http://localhost`, `tauri://localhost` and the
client''s registered redirect origins are allowed via CORS for public clients.'
security:
- {}
- clientSecretBasic: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: Tokens issued.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'400':
$ref: '#/components/responses/OAuthBadRequest'
'401':
$ref: '#/components/responses/OAuthInvalidClient'
'429':
$ref: '#/components/responses/OAuthRateLimited'
servers:
- url: https://auth.codai.ro
description: Production
/token/introspection:
post:
operationId: introspectToken
tags:
- Tokens
summary: Token introspection (RFC 7662)
description: 'Returns the state and claims of an access or refresh token. Requires client
authentication (same methods as `/token`). An unknown, expired or revoked token yields
`{ "active": false }` with `200`, not an error. codai''s own gateway verifies opaque
tokens here; MCP JWTs are verified locally against `/jwks` instead.'
security:
- clientSecretBasic: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- token
properties:
token:
type: string
token_type_hint:
type: string
enum:
- access_token
- refresh_token
client_id:
type: string
description: For `client_secret_post` / `none`.
client_secret:
type: string
description: For `client_secret_post`.
client_assertion_type:
type: string
description: For `private_key_jwt`.
client_assertion:
type: string
responses:
'200':
description: Introspection result (also for inactive tokens).
content:
application/json:
schema:
$ref: '#/components/schemas/IntrospectionResponse'
'400':
$ref: '#/components/responses/OAuthBadRequest'
'401':
$ref: '#/components/responses/OAuthInvalidClient'
servers:
- url: https://auth.codai.ro
description: Production
/token/revocation:
post:
operationId: revokeToken
tags:
- Tokens
summary: Token revocation (RFC 7009)
description: 'Revokes an access or refresh token issued to the authenticated client. Always answers
`200` with an empty body, even for unknown tokens. Revoking the OAuth **grant** (user
disconnects the app in the console) also revokes any API key minted via `/connect/key`.'
security:
- clientSecretBasic: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- token
properties:
token:
type: string
token_type_hint:
type: string
enum:
- access_token
- refresh_token
client_id:
type: string
client_secret:
type: string
client_assertion_type:
type: string
client_assertion:
type: string
responses:
'200':
description: Token revoked (or already invalid). Empty body.
'400':
$ref: '#/components/responses/OAuthBadRequest'
'401':
$ref: '#/components/responses/OAuthInvalidClient'
servers:
- url: https://auth.codai.ro
description: Production
components:
responses:
OAuthInvalidClient:
description: Client authentication failed (`invalid_client`).
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
OAuthRateLimited:
description: More than 60 requests per minute from one IP (`rate_limited`).
headers:
Retry-After:
schema:
type: string
const: '60'
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
OAuthBadRequest:
description: Malformed request, bad grant, invalid code_verifier, unsupported grant type, or device flow pending (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`).
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
schemas:
OAuthError:
type: object
title: OAuth error
description: RFC 6749 §5.2 error envelope, also used by the codai extensions on this host.
required:
- error
properties:
error:
type: string
description: Machine-readable code.
examples:
- invalid_request
- invalid_client
- invalid_grant
- invalid_token
- insufficient_scope
- authorization_pending
- slow_down
- rate_limited
error_description:
type: string
description: Human-readable detail.
IntrospectionResponse:
type: object
title: Introspection response
required:
- active
properties:
active:
type: boolean
scope:
type: string
client_id:
type: string
sub:
type: string
description: User id (UUID).
token_type:
type: string
exp:
type: integer
iat:
type: integer
iss:
type: string
format: uri
aud:
type: string
description: Resource indicator the token was minted for.
jti:
type: string
TokenRequest:
type: object
title: Token request
description: Form-encoded body. Fields depend on `grant_type`; client credentials depend on the client's authentication method.
required:
- grant_type
properties:
grant_type:
type: string
enum:
- authorization_code
- refresh_token
- urn:ietf:params:oauth:grant-type:device_code
code:
type: string
description: '`authorization_code` — the code from the redirect.'
redirect_uri:
type: string
format: uri
description: '`authorization_code` — must equal the value used at `/auth`.'
code_verifier:
type: string
description: '`authorization_code` — PKCE verifier (43–128 chars) whose S256 hash was sent as `code_challenge`.'
refresh_token:
type: string
description: '`refresh_token` grant.'
device_code:
type: string
description: '`device_code` grant — from `/device/auth`.'
scope:
type: string
description: Optional down-scoping on refresh.
resource:
type: string
format: uri
description: RFC 8707 resource indicator.
client_id:
type: string
description: Public clients (`none`) and `client_secret_post`.
client_secret:
type: string
description: '`client_secret_post` only.'
client_assertion_type:
type: string
const: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
description: '`private_key_jwt` only.'
client_assertion:
type: string
description: '`private_key_jwt` — JWT signed with a key from the client''s registered `jwks` / `jwks_uri`.'
TokenResponse:
type: object
title: Token response
required:
- access_token
- token_type
- expires_in
properties:
access_token:
type: string
description: Opaque (1 h), or an RS256 JWT when `resource=https://ai.codai.ro/mcp`.
token_type:
type: string
const: Bearer
expires_in:
type: integer
examples:
- 3600
scope:
type: string
description: Granted scopes, space-separated.
id_token:
type: string
description: Present when `openid` was granted. Includes `sub`, `role`, `sid`, `auth_time`, `acr`, `amr`, `nonce`.
refresh_token:
type: string
description: Only when the client allows `refresh_token` and `offline_access` was granted. Rotated on every refresh for public clients.
securitySchemes:
oauth2:
type: oauth2
description: codai OpenID Connect provider. PKCE `S256` required on the authorization code flow.
flows:
authorizationCode:
authorizationUrl: https://auth.codai.ro/auth
tokenUrl: https://auth.codai.ro/token
refreshUrl: https://auth.codai.ro/token
scopes:
openid: Verify your codai identity
profile: See your name and profile picture
email: See your email address
inference: Run AI inference through your codai account
keys:manage: Create and manage codai API keys on your behalf
usage:read: Read your codai usage statistics
subscriptions:read: Read your codai subscription plan
mcp: Use codai tools and memory from an MCP client
offline_access: Stay signed in on this device
deviceCode:
deviceAuthorizationUrl: https://auth.codai.ro/device/auth
tokenUrl: https://auth.codai.ro/token
scopes:
openid: Verify your codai identity
profile: See your name and profile picture
email: See your email address
inference: Run AI inference through your codai account
keys:manage: Create and manage codai API keys on your behalf
usage:read: Read your codai usage statistics
subscriptions:read: Read your codai subscription plan
mcp: Use codai tools and memory from an MCP client
offline_access: Stay signed in on this device
bearerAuth:
type: http
scheme: bearer
description: OAuth access token issued by `/token` (used by `/me` and `/connect/key`).
clientSecretBasic:
type: http
scheme: basic
description: '`client_secret_basic` client authentication. `client_secret_post` and `private_key_jwt` go in the form body instead; public clients send only `client_id`.'
x-refined-from:
- codai-ro-auth-openapi.json
- codai-ro-auth-openapi.yml