Koo Docs
View as Markdown

OAuth

Describe an in-flight OAuth login request for the console login screen

GET/oauth/login-request
Parameters
challengestringqueryrequired

The Hydra login_challenge from the authorize redirect.

Returns
200 · OauthLoginRequestViewDto422 · ErrorEnvelopeDto429 · ErrorEnvelopeDto
clientobjectread-only

The OAuth client requesting access (self-declared metadata — show, never trust).

requestedScopestring[]read-only

The OAuth scopes the client asked for (informational — authority comes from consent).

cURL
GET /oauth/login-request
bash
curl https://api.koo.io/oauth/login-request?challenge=example \  -H "Authorization: Bearer kc_your_api_token"
Response
json
{  "client": {    "clientId": "client_01example0000000000000000x",    "clientName": "example",    "clientUri": "example",    "logoUri": "example"  },  "requestedScope": [    "example"  ]}

Accept an OAuth login request as the signed-in user (subject-bound)

POST/oauth/login/complete
Request body
loginChallengestringrequired

The Hydra login challenge being accepted.

Returns
200 · OauthRedirectDto401 · ErrorEnvelopeDto403 · ErrorEnvelopeDto422 · ErrorEnvelopeDto
redirectTostring <uri>read-only

Where to navigate next to continue the OAuth flow.

cURL
POST /oauth/login/complete
bash
curl https://api.koo.io/oauth/login/complete \  -X POST \  -H "Authorization: Bearer kc_your_api_token" \  -H "Content-Type: application/json" \  -d '{      "loginChallenge": "example"    }'
Response
json
{  "redirectTo": "https://example.com"}

Reject (cancel) an OAuth login request — the client receives access_denied

POST/oauth/login/reject
Request body
loginChallengestringrequired

The Hydra login challenge being rejected.

Returns
200 · OauthRedirectDto422 · ErrorEnvelopeDto
redirectTostring <uri>read-only

Where to navigate next to continue the OAuth flow.

cURL
POST /oauth/login/reject
bash
curl https://api.koo.io/oauth/login/reject \  -X POST \  -H "Authorization: Bearer kc_your_api_token" \  -H "Content-Type: application/json" \  -d '{      "loginChallenge": "example"    }'
Response
json
{  "redirectTo": "https://example.com"}

Describe an in-flight OAuth consent request: client + the signed-in user’s grantable accounts

GET/oauth/consent-request
Parameters
challengestringqueryrequired

The Hydra consent_challenge from the authorize redirect.

Returns
200 · OauthConsentRequestViewDto401 · ErrorEnvelopeDto403 · ErrorEnvelopeDto422 · ErrorEnvelopeDto
clientobjectread-only

The OAuth client requesting access (self-declared metadata — show, never trust).

requestedScopestring[]read-only

The OAuth scopes the client asked for (informational — authority comes from consent).

requestedAudiencestring[]read-only

The access-token audience(s) the client requested (the MCP resource URLs).

accountsobject[]read-only

The signed-in user’s accounts — consent grants access to exactly ONE of them.

cURL
GET /oauth/consent-request
bash
curl https://api.koo.io/oauth/consent-request?challenge=example \  -H "Authorization: Bearer kc_your_api_token"
Response
json
{  "client": {    "clientId": "client_01example0000000000000000x",    "clientName": "example",    "clientUri": "example",    "logoUri": "example"  },  "requestedScope": [    "example"  ],  "requestedAudience": [    "example"  ],  "accounts": [    {      "id": "acct_01example0000000000000000x",      "handle": "alice",      "displayName": "My app",      "myRole": "owner",      "grantableRoles": [        "reader"      ]    }  ]}

Grant the client access to ONE account at a capped machine role (reader/editor)

POST/oauth/consent/complete
Request body
consentChallengestringrequired

The Hydra consent challenge being accepted.

accountIdstringrequired

The single account this grant confers access to.

role"reader" | "editor"required

Token role: `editor` (Write) can deploy and manage services; `reader` (Read) is view-only.

Returns
200 · OauthRedirectDto401 · ErrorEnvelopeDto403 · ErrorEnvelopeDto422 · ErrorEnvelopeDto
redirectTostring <uri>read-only

Where to navigate next to continue the OAuth flow.

cURL
POST /oauth/consent/complete
bash
curl https://api.koo.io/oauth/consent/complete \  -X POST \  -H "Authorization: Bearer kc_your_api_token" \  -H "Content-Type: application/json" \  -d '{      "consentChallenge": "example",      "accountId": "acct_01example0000000000000000x",      "role": "reader"    }'
Response
json
{  "redirectTo": "https://example.com"}

Reject (deny) an OAuth consent request — the client receives access_denied

POST/oauth/consent/reject
Request body
consentChallengestringrequired

The Hydra consent challenge being rejected.

Returns
200 · OauthRedirectDto422 · ErrorEnvelopeDto
redirectTostring <uri>read-only

Where to navigate next to continue the OAuth flow.

cURL
POST /oauth/consent/reject
bash
curl https://api.koo.io/oauth/consent/reject \  -X POST \  -H "Authorization: Bearer kc_your_api_token" \  -H "Content-Type: application/json" \  -d '{      "consentChallenge": "example"    }'
Response
json
{  "redirectTo": "https://example.com"}

The MCP clients you have authorized (from Hydra’s consent sessions)

GET/me/mcp-grants
Returns
200 · McpGrantDto[]401 · ErrorEnvelopeDto403 · ErrorEnvelopeDto
cURL
GET /me/mcp-grants
bash
curl https://api.koo.io/me/mcp-grants \  -H "Authorization: Bearer kc_your_api_token"
Response
json
[  {    "clientId": "client_01example0000000000000000x",    "clientName": "example",    "accountId": "acct_01example0000000000000000x",    "accountHandle": "example",    "role": "reader",    "grantedAt": "2026-01-01T00:00:00.000Z"  }]

Revoke an MCP client’s grant — new requests stop immediately; issued tokens expire within 1 hour

DELETE/me/mcp-grants/{clientId}
Parameters
clientIdstringpathrequired

The authorized OAuth client id to revoke.

Returns
204401 · ErrorEnvelopeDto403 · ErrorEnvelopeDto
cURL
DELETE /me/mcp-grants/{clientId}
bash
curl https://api.koo.io/me/mcp-grants/:clientId \  -X DELETE \  -H "Authorization: Bearer kc_your_api_token"

RFC 7591 dynamic client registration (hardened proxy in front of Hydra)

POST/oauth/register
Returns
201400
cURL
POST /oauth/register
bash
curl https://api.koo.io/oauth/register \  -X POST \  -H "Authorization: Bearer kc_your_api_token" \  -H "Content-Type: application/json" \  -d '{      "key": "example"    }'

RFC 7592 client read — not offered (this server issues no registration access tokens)

GET/oauth/register/{clientId}
Parameters
clientIdstringpathrequired

The registered OAuth client id.

Returns
404
cURL
GET /oauth/register/{clientId}
bash
curl https://api.koo.io/oauth/register/:clientId \  -H "Authorization: Bearer kc_your_api_token"

RFC 7592 client update — not offered (this server issues no registration access tokens)

PUT/oauth/register/{clientId}
Parameters
clientIdstringpathrequired

The registered OAuth client id.

Returns
404
cURL
PUT /oauth/register/{clientId}
bash
curl https://api.koo.io/oauth/register/:clientId \  -X PUT \  -H "Authorization: Bearer kc_your_api_token" \  -H "Content-Type: application/json" \  -d '{      "key": "example"    }'

RFC 7592 client deprovision — not offered (this server issues no registration access tokens)

DELETE/oauth/register/{clientId}
Parameters
clientIdstringpathrequired

The registered OAuth client id.

Returns
404
cURL
DELETE /oauth/register/{clientId}
bash
curl https://api.koo.io/oauth/register/:clientId \  -X DELETE \  -H "Authorization: Bearer kc_your_api_token"