OAuth 2.0

Register an application

Applications are registered inside the Kyo app under Settings → API (workspace admins). Registration is self-serve and gives you a client id (kyoapp_…) plus up to 10 redirect URIs.

• Public clients — desktop, CLI, and mobile apps that can't keep a secret. No client secret is issued; PKCE alone protects the exchange.
• Confidential clients — server-side apps. A client secret (kyo_sk_…) is shown once at creation and stored only as a hash — save it immediately.

Dynamic registration

Clients that can't be pre-registered by an admin — MCP connectors and agent tooling, above all — can register themselves with RFC 7591 dynamic client registration. No authentication is needed: registration grants nothing by itself, since the user still approves every scope on the consent screen.

curl -X POST "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/oauth-register" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Agent",
    "redirect_uris": ["https://myagent.example/callback"],
    "token_endpoint_auth_method": "none"
  }'

{
  "client_id": "kyoapp_…",
  "client_id_issued_at": 1771000000,
  "client_name": "My Agent",
  "redirect_uris": ["https://myagent.example/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "deals:read deals:write …"
}

• Public clients only. token_endpoint_auth_method must be "none" — no client secret is ever issued this way. Confidential apps are registered in Settings → API.
• redirect_uris is required, max 10, each https or a localhost/127.0.0.1 loopback URL with no fragment.
• scope is optional. Omit it and the client may request the full catalogue; the user decides what is actually granted.
• logo_uri and client_uri are shown on the consent screen and must be https.
• Dynamically registered clients are always unverified, so users see the warning banner. Registration is rate-limited to 20 per hour per IP.

Discovery

Both metadata documents are served from the app origin, so a client can find every endpoint on this page automatically:

https://app.trykyo.com/.well-known/oauth-authorization-server
https://app.trykyo.com/.well-known/oauth-protected-resource

The first is RFC 8414 authorization-server metadata (authorization, token, registration and revocation endpoints, S256 only, supported scopes). The second is RFC 9728 protected-resource metadata for the hosted MCP server — an unauthenticated call to it also returns a WWW-Authenticate header pointing here, which is how MCP clients start the flow on their own.

Endpoints

Token and revocation requests are form-encoded POSTs and also need the public apikey header — the same anon key used for REST API requests. (JSON bodies are accepted too, as a convenience.) Registration takes JSON and needs no headers beyond Content-Type. Only S256 PKCE is supported — plain is rejected.

Authorization flow

Before starting, generate a PKCE pair: a random code_verifier (43–128 characters) and its code_challenge = base64url(SHA-256(verifier)). Only the S256 challenge method is accepted.

1. Send the user to the consent screen

https://app.trykyo.com/oauth/authorize
  ?client_id=kyoapp_…
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=deals:read%20tasks:write
  &state=…
  &code_challenge=…
  &code_challenge_method=S256

The user signs in to Kyo (if needed), reviews the requested scopes, and approves. Kyo redirects back to your redirect_uri with ?code=kyo_ac_…&state=…. Always verify state matches what you sent.

2. Exchange the code for tokens

curl -X POST "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/oauth-token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "apikey: $KYO_ANON_KEY" \
  -d grant_type=authorization_code \
  -d code=kyo_ac_… \
  -d code_verifier=… \
  -d client_id=kyoapp_… \
  -d redirect_uri=https://yourapp.com/callback

{
  "access_token": "kyo_at_…",
  "refresh_token": "kyo_rt_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "deals:read tasks:write"
}

Confidential clients also authenticate this request — either HTTP Basic (client_id:client_secret) or a client_secret body parameter. The PKCE code_verifier is required for all clients. OAuth errors use the standard { "error": "…", "error_description": "…" } shape.

3. Call the API

curl "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/api-v1/v1/deals" \
  -H "Authorization: Bearer kyo_at_…" \
  -H "apikey: $KYO_ANON_KEY"

See the REST API reference for everything you can call.

Refreshing tokens

Access tokens live for 1 hour. Use the refresh grant to get a new pair:

curl -X POST "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/oauth-token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "apikey: $KYO_ANON_KEY" \
  -d grant_type=refresh_token \
  -d refresh_token=kyo_rt_… \
  -d client_id=kyoapp_…

• Rotation — every refresh returns a new access + refresh pair and invalidates the old refresh token. Always persist the new one.
• Reuse detection — replaying an already-rotated refresh token is treated as a compromise: the entire token family is revoked and the user must authorize again.
• Scope narrowing — pass scope to downgrade; scopes can never be widened on refresh.

Refresh tokens expire after 30 days.

Revoking access

Kyo implements RFC 7009 token revocation:

curl -X POST "https://pvozbkuhjofzitsmpspf.supabase.co/functions/v1/oauth-revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "apikey: $KYO_ANON_KEY" \
  -d token=kyo_rt_… \
  -d token_type_hint=refresh_token \
  -d client_id=kyoapp_…

Revoking a refresh token revokes its whole family. Users can also revoke any authorized app themselves from Settings → API in Kyo.

Scopes

Request scopes as a space-separated list. Scopes are resource:read / resource:write; the wildcard resource:* is also accepted. A token can never exceed what the authorizing user can do in the app — see permissions. There is no :delete scope: v1 of the API cannot delete anything.

Token reference

Kyo tokens are opaque strings, not JWTs — don't try to decode them. They're stored hashed at rest on Kyo's side; treat them like passwords on yours.

Redirect URI rules

• https is required for web apps, and matching is exact — scheme, host, path, and query.
• Loopback is allowed for native apps — http://127.0.0.1 and http://localhost URIs may use any ephemeral port: the port is ignored at match time (RFC 8252), so register http://127.0.0.1/callback once.
• No URL fragments; up to 10 URIs per application.