# Tokoserver agent API v1

Public guide: https://tokoserver.com/agents
OpenAPI: https://tokoserver.com/openapi.json
API base: https://api.tokoserver.com/api/v1/agent/v1
OAuth configuration: https://api.tokoserver.com/api/v1/sso/config

Supported client: registered public OAuth client with exact redirect URI, authorization code, PKCE S256, and a local callback receiver. Organization administrators register clients at https://app.tokoserver.com/user/connected-agents. No client secret or Tokoserver-specific software is needed. A general HTTP client and SHA-256 are required. Never collect the user's Tokoserver password.

Authorization: Fetch /api/v1/sso/config to find the Hydra authorization and token URLs. Send response_type=code, registered client_id and redirect_uri, requested scope, random state, S256 code_challenge, and code_challenge_method=S256. The user signs in and approves on the Tokoserver-hosted consent page. Check state at callback; exchange the code with the original code_verifier. Bearer access tokens are short lived and agent clients do not get refresh tokens. Do not place tokens in URLs, logs, browser localStorage, or chat.

Scopes: openid is required. application:read enables GET /applications and GET /applications/{id}. deployment:read enables GET /deployments/{id}. Scope does not override current organization membership or IAM. Tokens are bound to the client's organization, even if the user belongs to more than one. Optional X-Organization-Id must match that organization.

GET https://api.tokoserver.com/api/v1/agent/v1/capabilities
Public versioned operation availability. Check this before attempting an agent workflow.

GET https://api.tokoserver.com/api/v1/agent/v1/applications
Returns up to 100 accessible projects with id, name, status, repositoryFullName, branch, deploymentUrl, createdAt. Requires application:read and deployment.projects.list IAM.

GET https://api.tokoserver.com/api/v1/agent/v1/applications/{id}
Returns non-secret project metadata. Requires application:read and deployment.projects.get IAM for that project.

GET https://api.tokoserver.com/api/v1/agent/v1/deployments/{id}
Returns id, application_id, status, timestamps, and application_url when the actual deployment succeeded. Requires deployment:read and deployment.projects.get IAM for the parent project. Status values follow the existing Tokoserver deployment lifecycle.

Errors: {"error":{"code":"INVALID_TOKEN","message":"...","retryable":false}}. 401 invalid/expired token; 403 revoked client, missing scope, missing membership/IAM, or wrong organization; 404 inaccessible resource; 503 authorization provider unavailable. The read API allows 120 requests per token and 300 per IP per minute. On 429, wait for Retry-After.

Revoke: Organization administrator opens Connected AI Agents & Applications and revokes the registered client. Tokoserver rejects revoked clients even if Hydra has not yet deleted the client.

Unavailable: RFC 8628 device flow, deployment planning, deployment execution, billable approval, agent-readable logs, and agent database provisioning. Do not call existing dashboard resource creation endpoints with agent tokens. Node.js, Docker, and PostgreSQL deployment walkthroughs await a protected execution and billing approval flow; product guides at https://tokoserver.com/id-id/products/auto-deployment and https://tokoserver.com/id-id/products/database-services describe dashboard workflows only.