API ReferenceAgent Auth

Connect an Azure OpenAI deployment (org-level)

Validates endpoint_url + deployment_name + api_key against the real Azure resource, then stores it as this org’s Azure OpenAI credential. Every future Codex run for this org routes through this deployment.

Scope: agent_auth:write

Authentication

AuthorizationBearer

Your ara_ API key from Settings > Ara API. Keys are capability-scoped: run, plugins:read, secrets:read, secrets:write, sessions:read, knowledge:read, repos:read, repos:write, reviews:read, reviews:write, analytics:read, org:read, org:write, attachments:read, attachments:write, plugins:write, guardrails:read, guardrails:write.

Path parameters

orgIdstringRequired

Organization id or slug. Resolve it with GET /v3/self.

Request

This endpoint expects an object.
endpoint_urlstringRequired

The Azure OpenAI / AI Foundry resource endpoint, e.g. https://YOUR_RESOURCE_NAME.openai.azure.com.

deployment_namestringRequired

The deployment name YOU gave this model in Azure AI Foundry — not the underlying model name.

api_keystringRequired

One of the resource’s two API keys (Keys and Endpoint page). Stored encrypted, never returned. Omit when connecting via Entra ID instead.

tenant_idstringOptional

Azure AD tenant (directory) ID. Send with client_id + client_secret instead of api_key to connect via Entra ID.

client_idstringOptional

The Entra ID app registration’s client (application) ID.

client_secretstringOptional
The Entra ID app registration's client secret value. Stored encrypted, never returned.

Response

Connected.

Errors

400
Bad Request Error