Create API keys and connect agents

1. 1

   Verify the server-wide gate

   A server administrator opens General Settings and confirms openai_proxy_enabled is enabled. The server rejects the compatible API with 403 feature_disabled when this gate is off.

2. 2

   Enable the organization policy

   Open Integrations → API Keys & Agents at /api-keys, choose the organization, and enable API keys. When disabled, requests return 403 org_feature_disabled.

3. 3

   Create the appropriate owner type

   Organization administrators can create organization-owned shared keys at /api-keys. When organization policy permits member keys, a member manages a member-owned key from the API Keys card on /dashboard.

4. 4

   Restrict and store the key

   Choose the smallest useful model allowlist and expiry. Set a daily token or daily cost budget and choose the active quota unit. Copy a revealed secret into a secret manager; never put it in source control or browser-delivered code.

Set the base URL to your Orchestris Server origin followed by /openai/v1. Send the API key as Authorization: Bearer <key> on every request.

export ORCHESTRIS_BASE_URL="https://chat.example.com/openai/v1"
export ORCHESTRIS_API_KEY="replace-with-the-revealed-secret"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ORCHESTRIS_API_KEY" \
  "$ORCHESTRIS_BASE_URL/models"

Use an id returned by this request as the model value in later calls. If an expected model is missing, check provider/model activation, member group grants, alias state, and the API-key allowlist in that order.

The response includes data, has_more, and, when another page exists, an opaque last_id cursor. If has_more is true, copy last_id exactly into the next request's after query parameter. Continue until has_more is false; do not parse, modify, or derive the cursor.

export ORCHESTRIS_MODELS_AFTER="<LAST_ID_FROM_PREVIOUS_RESPONSE>"
curl --get --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ORCHESTRIS_API_KEY" \
  --data-urlencode "after=$ORCHESTRIS_MODELS_AFTER" \
  "$ORCHESTRIS_BASE_URL/models"

curl --fail-with-body --silent --show-error \
  -X POST "$ORCHESTRIS_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ORCHESTRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "replace-with-an-id-from-models",
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ]
  }'

curl --no-buffer --fail-with-body --silent --show-error \
  -X POST "$ORCHESTRIS_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ORCHESTRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "replace-with-an-id-from-models",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from one to three."}
    ]
  }'

A request with stream: true returns Server-Sent Events. Keep the HTTP connection open and process events incrementally.

curl --fail-with-body --silent --show-error \
  -X POST "$ORCHESTRIS_BASE_URL/responses" \
  -H "Authorization: Bearer $ORCHESTRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "replace-with-an-id-from-models",
    "input": "Reply with one short sentence."
  }'

The Responses route also supports stream: true over Server-Sent Events. Support is intentionally limited to fields accepted by the current Orchestris implementation; an unknown field returns invalid_request_error.

After a curl request succeeds, configure any client that supports an OpenAI-compatible endpoint with the same values. Field names differ between clients, but the four values below do not.

• Send a unique UUID as x-request-id that does not contain credentials or personal data. The server echoes x-request-id on the response and generates one when the client omits it.
• A key using the tokens quota unit enforces a daily token budget. A key using the cost_usd quota unit enforces a daily cost budget.
• Both token and cost usage counters refresh at the organization's local day boundary. An administrator can explicitly reset usage to clear the current-day counter.
• The key allowlist is evaluated in addition to provider/model state and the owner's model visibility.
• Expiration and revocation stop future authentication. Rotate a key when exposure is suspected rather than waiting for expiry.
• OpenAI-compatible quota failures use the compatible 429 too_many_requests response. Native server quota and license request-limit errors use 402; see the troubleshooting article for the protocol distinction.

• Orchestris does not currently publish an official SDK. You may configure a third-party OpenAI-compatible client against the base URL, but compatibility beyond the documented fields is not guaranteed.
• Orchestris does not currently provide customer-configurable outbound webhooks.
• Portal licensing and billing routes are for deployment operations, not agent integrations.
• Use HTTP Server-Sent Events for agent streaming; do not integrate an agent with the native Chat WebSocket.