Quickstart

This is the shortest server-side path for a web open agent to use the current subject's model entitlement. OAuth tokens, client secrets, and authorization codes must stay on trusted servers.

1. Register the agent

Provide the agent name, exact HTTPS entry or redirect URI, required scopes, allowed web origins or MCP endpoint, and review metadata. A client secret is shown only when created or rotated; store it in a secret manager immediately.

2. Request the right context

Personal model access requires at least:

profile model

Add balance, usage, or charge only when the product needs them. Team access must specify the target team_id and request team_read or team_manage as appropriate.

3. Exchange the authorization code

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=<client-id>&client_secret=<client-secret>&code=<single-use-code>&redirect_uri=<registered-redirect-uri>

A new code exchange produces a 7-day access token and no new refresh token. Re-authorize after expiry or revocation.

4. List models

GET /api/v1/open/models
Authorization: Bearer <personal-access-token>

For a Team-bound token:

GET /api/v1/open/teams/<team-id>/models
Authorization: Bearer <team-access-token>

Use only the returned modelCode and parameterSpec.

5. Call the gateway

POST /api/proxy/v1/chat/completions
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "model": "<modelCode>",
  "messages": [{ "role": "user", "content": "Hello" }],
  "stream": true
}

Personal tokens support streaming. Team tokens require trusted workflow headers and currently require "stream": false.

Open APIs use { success, data, request_id } on success and { success, code, message, request_id } on failure. Log only the stable code and request ID.