codai Tokens API

Token issuance, introspection (RFC 7662) and revocation (RFC 7009).

GitHub OpenAPI

Operations 3

POST /token Token endpoint #
POST /token/introspection Token introspection (RFC 7662) #
POST /token/revocation Token revocation (RFC 7009) #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/codai-ro:codai-ro-tokens-api"
All apis
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.

Get an API 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 Specification

codai-ro-tokens-api-openapi.yml Raw ↑
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