Agentdisco Io Authentication

generated: '2026-09-19'
method: searched
docs: https://agentdisco.io/developers
source: >-
  https://agentdisco.io/developers, https://agentdisco.io/llms.txt, the operation descriptions in
  openapi/agentdisco-io-openapi.yml (harvested from https://agentdisco.io/api/v1/openapi.json - whose
  components.securitySchemes is null, which is why derive-authentication.py produced nothing), GET
  https://agentdisco.io/api/v1/auth/colony/agent (200, observed 2026-09-19), the 401 bodies observed on
  GET /api/v1/webhooks, /api/v1/keys and /api/v1/ops/version, and
  https://thecolony.ai/.well-known/openid-configuration.
summary: >-
  Bearer API keys (prefix ak_) with three quota tiers, obtainable three ways - anonymously with one POST,
  by signing in on the website, or non-interactively by an autonomous agent presenting an RFC 8693 id_token
  minted at The Colony. Most reads and scan submission need no credential at all. There is no OAuth
  authorization server on agentdisco.io itself; the Colony is a third-party issuer and Agent Disco is a
  relying party. Two operator endpoints use HTTP Basic.
schemes:
- id: bearerApiKey
  type: http
  scheme: bearer
  bearer_format: 'ak_ token (first 10 chars, e.g. ak_XXXXXXX, are the loggable tokenPrefix)'
  header: 'Authorization: Bearer ak_...'
  declared_in_spec: false
  applies_to:
    optional: [post_api_scan_create, post_api_website_rescan]
    required_account_bound: [get_api_key_list, delete_api_key_revoke, get_api_webhook_list, post_api_webhook_create, delete_api_webhook_delete]
  obtain:
  - method: anonymous mint
    operation: post_api_key_create
    detail: 'POST /api/v1/keys with no credential ("No account, no email - just click the button"); optional {label}; 201 returns the plaintext token ONCE plus id, tokenPrefix, rateLimitTier anonymous; 5 mints/hour per IP.'
  - method: website sign-in
    url: https://agentdisco.io/register
    detail: Keys created from /account are bound to the account (rateLimitTier authenticated); the account activity log records key and webhook creation.
  - method: Colony agent sign-in
    operation: post_api_colony_agent_login
    detail: See colony_token_exchange below; returns an account-bound authenticated-tier key.
  tiers:
  - {tier: anonymous (no key), quota: 10 scans/day per IP}
  - {tier: anonymous key, quota: 100 scans/day per key, note: cannot own webhooks or list keys - 401 "Anonymous keys can't own webhooks"}
  - {tier: authenticated (account-bound key), quota: 500 scans/day per key}
  revocation: DELETE /api/v1/keys/{id} - idempotent, immediate; a revoked key drops to the anonymous limit; you may revoke the key you authenticate with.
  storage: The server keeps only a hash; plaintext is never returned after mint (GET /api/v1/keys shows tokenPrefix only).
- id: opsBasic
  type: http
  scheme: basic
  realm: ops
  declared_in_spec: referenced by two operations but undefined (components.securitySchemes is null)
  applies_to: [get_api_ops_check_health, get_api_ops_version]
  detail: 'Operator-only; credentials are the deployment''s OPS_BASIC_AUTH_USER / OPS_BASIC_AUTH_PASS env vars, not issued to API consumers. Observed: 401 with WWW-Authenticate: Basic realm="ops".'
- id: none
  type: none
  applies_to: [get_openapi_spec, get_api_checks_index, get_api_scan_show, get_api_scan_diff, get_api_website_show, get_api_website_scans, get_api_website_badge, get_api_website_badge_png, get_api_colony_agent_login_discovery, post_api_key_create, post_api_website_unlist_request, post_api_website_unlist_confirm, post_api_website_relist_request, post_api_website_relist_confirm, delete_api_website_delete]
  detail: Public reads, key mint, the DNS-TXT-verified unlist/relist flow and the right-to-delete endpoint are unauthenticated and rate-limited per IP.
colony_token_exchange:
  standard: OAuth 2.0 Token Exchange (RFC 8693)
  role_of_agentdisco: relying party / audience
  issuer: https://thecolony.ai
  token_endpoint: https://thecolony.ai/oauth/token
  audience: colony_gNvs-06hD2sPmBWHgQ4skwGUMpDwqmcl
  grant_type: urn:ietf:params:oauth:grant-type:token-exchange
  subject_token_type: urn:ietf:params:oauth:token-type:access_token
  requested_token_type: urn:ietf:params:oauth:token-type:id_token
  scope: openid profile
  discovery: GET https://agentdisco.io/api/v1/auth/colony/agent (get_api_colony_agent_login_discovery) publishes all of the above; cacheable, static per deployment.
  exchange_endpoint: 'POST https://agentdisco.io/api/v1/auth/colony/agent with {"id_token": "..."}'
  responses:
    201: authenticated-tier ak_ key shown once
    400: missing id_token
    401: invalid/expired token, wrong audience, or a non-agent (human) subject
    404: Colony login disabled on this deployment
    429: too many attempts from this IP
  rules:
  - Only an id_token audienced to AgentDisco is accepted; never send the raw Colony credential.
  - Agent-only - human Colony subjects are rejected; humans use "Log in with the Colony" on the website.
  - The Python SDK (>=0.4.0) runs the exchange at the Colony itself (AgentDisco.from_colony_token).
  colony_metadata:
    file: well-known/agentdisco-io-colony-openid-configuration.json
    registration_endpoint: https://thecolony.ai/oauth/register
    pkce: S256
    grant_types_supported: [authorization_code, refresh_token, 'urn:ietf:params:oauth:grant-type:token-exchange', 'urn:openid:params:grant-type:ciba', 'urn:ietf:params:oauth:grant-type:device_code']
own_oauth_metadata:
  openid_configuration: 404
  oauth_authorization_server: 404
  oauth_protected_resource: 404
  note: Agent Disco publishes no RFC 8414 / RFC 9728 / OIDC discovery of its own; it issues opaque ak_ keys, not OAuth tokens.
delegated_identity:
  supported: true
  mechanism: Colony identity -> RFC 8693 token exchange -> account-bound ak_ key
  human_in_loop: none required for agents holding a Colony identity
website_accounts:
  sign_up: https://agentdisco.io/register
  login: https://agentdisco.io/login
  detail: Password accounts with optional 2FA and a per-user activity log at /account/activity (privacy policy section 2); "Log in with the Colony" is offered to humans.
related:
  conventions: conventions/agentdisco-io-conventions.yml
  rate_limits: rate-limits/agentdisco-io-rate-limits.yml
  overlay_adding_securitySchemes: overlays/agentdisco-io-openapi-overlay.yaml