codai Connect API
codai extension — exchange an access token for an inference API key.
codai extension — exchange an access token for an inference API key.
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-connect-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 Connect API
version: '1'
description: 'Operations tagged Connect 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: Connect
description: codai extension — exchange an access token for an inference API key.
paths:
/connect/key:
get:
operationId: connectKey
tags:
- Connect
summary: Exchange an access token for a codai inference key
description: 'codai-specific. Send the access token from `/token` as `Authorization: Bearer`. The
grant must include `inference` or `keys:manage`. On the **first** call codai mints a
scoped inference key bound to the grant and returns the plaintext in `api_key`; every
later call for the same grant returns `api_key: null`, `already_issued: true` and the
same `api_key_id` — the plaintext is never stored, so persist it immediately. Exception:
first-party codai clients (desktop app) get a fresh key on every sign-in, labelled with
the `X-Codai-Device-Name` header, because they share one grant per user. Revoking the
grant revokes the key. Browser callers need an allow-listed `Origin` (see `OPTIONS`).'
security:
- bearerAuth: []
parameters:
- name: X-Codai-Device-Name
in: header
required: false
description: First-party clients only — label (≤ 60 chars) for the per-device key; defaults to `Desktop`.
schema:
type: string
maxLength: 60
responses:
'200':
description: Key minted (first call) or already issued.
headers:
Access-Control-Allow-Origin:
description: Echoed only for allow-listed browser origins.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectKeyResponse'
'400':
description: '`invalid_grant` — the token has no grant attached.'
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
'401':
$ref: '#/components/responses/OAuthInvalidToken'
'403':
description: '`insufficient_scope` — token or grant lacks `keys:manage` / `inference`.'
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
options:
operationId: connectKeyPreflight
tags:
- Connect
summary: CORS preflight for /connect/key
description: 'Browser preflight. Allow-listed origins (`https://app.codai.ro`, `http://localhost:5180`,
`http://127.0.0.1:5180`, plus the `CONNECT_KEY_CORS_ORIGINS` deployment list) receive
`204` with `Access-Control-Allow-Origin: `, `Access-Control-Allow-Methods: GET,
OPTIONS`, `Access-Control-Allow-Headers: authorization, content-type,
x-codai-device-name` and `Access-Control-Max-Age: 86400`. Any other origin gets `403`
`{ "error": "origin_not_allowed" }`. Without an `Origin` header the answer is `204`
with `Allow: GET, OPTIONS`.'
parameters:
- name: Origin
in: header
required: false
schema:
type: string
format: uri
responses:
'204':
description: Preflight accepted.
headers:
Access-Control-Allow-Origin:
schema:
type: string
Access-Control-Allow-Methods:
schema:
type: string
const: GET, OPTIONS
Access-Control-Allow-Headers:
schema:
type: string
const: authorization, content-type, x-codai-device-name
Access-Control-Max-Age:
schema:
type: string
const: '86400'
'403':
description: Origin is not on the allow-list.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
const: origin_not_allowed
servers:
- url: https://auth.codai.ro
description: Production
/connect/github:
post:
operationId: connectGithub
tags:
- Connect
summary: Exchange a VS Code GitHub token for a codai inference key
description: 'First-party (codai VS Code extension). Send the GitHub OAuth access token VS Code obtained with
`vscode.authentication.getSession(''github'', [''read:user'',''user:email''])`. codai verifies it against
`api.github.com/user`, accepts only tokens issued to VS Code''s built-in GitHub app or codai''s own
GitHub app (personal access tokens are refused), resolves the account exactly like GitHub sign-in on the
web (existing link first, else the verified GitHub email; a new account is created like the web flow) and
mints a fresh inference key labelled `VS Code ()` on every call — persist it. Accounts with a
second factor (or required to have one) get `403 account_not_allowed` and must use the device flow.
Rate limit: 20 requests/minute per IP. The GitHub token is never logged or stored.'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- access_token
properties:
access_token:
type: string
description: GitHub OAuth access token from VS Code.
device_name:
type: string
maxLength: 60
platform:
type: string
enum:
- vscode
device_id:
type: string
maxLength: 64
description: Stable per-install id (VS Code machine id derived UUID) recorded on the key for per-device usage. Falls back to the `x-codai-device` header.
responses:
'200':
description: Key minted.
content:
application/json:
schema:
type: object
required:
- key
- api_key_id
- base_url
- model
- user
properties:
key:
type: string
description: Plaintext codai inference key (shown once).
api_key_id:
type: string
base_url:
type: string
format: uri
model:
type: string
const: codai
user:
type: object
required:
- id
properties:
id:
type: string
email:
type:
- string
- 'null'
name:
type:
- string
- 'null'
'400':
description: '`invalid_request` — missing or malformed body.'
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
'401':
description: '`invalid_github_token` — GitHub rejected the token, or it was not issued to an allowed app.'
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
'403':
description: '`email_unverified` or `account_not_allowed` (disabled account, or second factor required).'
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
'404':
description: GitHub sign-in is not configured on this deployment.
'429':
description: Rate limited (20/min per IP).
'502':
description: '`github_unavailable` — GitHub did not answer in time.'
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
servers:
- url: https://auth.codai.ro
description: Production
components:
responses:
OAuthInvalidToken:
description: Missing, unknown or expired bearer token (`invalid_token`).
headers:
WWW-Authenticate:
schema:
type: string
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.
ConnectKeyResponse:
type: object
title: Connect key response
required:
- api_key
- api_key_id
- base_url
- model
- already_issued
properties:
api_key:
type:
- string
- 'null'
description: Plaintext key, returned **only once** per grant (`null` afterwards). Store it sealed.
examples:
- codai_xxxxxxxxxxxxxxxxxxxxxxxx
api_key_id:
type: string
format: uuid
description: Stable id of the minted key (revocable from the console).
base_url:
type: string
format: uri
const: https://ai.codai.ro/v1
description: OpenAI-compatible base URL to use the key against.
model:
type: string
const: codai
already_issued:
type: boolean
description: '`true` when the plaintext was already handed out on an earlier call.'
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