> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkato.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth authorization

> Consent, PKCE, token rotation, and compatibility paths for registered clients.

Kato uses authorization codes with **PKCE S256** for its registered Raycast client. The current client ID is `kato-raycast`. These endpoints document the existing integration protocol; there is no public client-registration endpoint or arbitrary redirect registration.

## Authorization flow

1. Read [client metadata](/api-reference/oauth/client) to display the integration name and requested scopes.
2. The client generates a random verifier, its S256 challenge, and a unique `state` value. Retain the original verifier and state for that authorization attempt.
3. A signed-in Kato user selects a workspace and consents. The application calls [Authorize a workspace grant](/api-reference/oauth/authorize) using the user's session. This endpoint requires a session, not an API key.
4. The response contains `redirectUrl`. Navigate the user to that URL. The client must verify the returned state matches its original value before exchanging the code.
5. Call [Exchange or refresh tokens](/api-reference/oauth/token) with the code, original verifier, client ID, and exact redirect URI. Codes expire after **five minutes** and can be used once.
6. Store both tokens securely. Send the access token to the [Raycast API](/api-reference/raycast/overview).

The registered redirect is the Raycast redirect URL on `raycast.com` or `www.raycast.com`, with an allowed `packageName` of `Extension` or `kato` (case-insensitive for `kato`). Supplying a different callback URL does not register it.

## Token lifetime and refresh

Access tokens last **one hour**. Use `expires_in` from the exchange response to calculate expiry. The refresh grant starts with a **365-day** lifetime; use `refresh_token_expires_in` for its remaining lifetime.

A successful refresh returns a new access token **and a new refresh token**, and revokes previous access tokens for that grant. Serialize refresh attempts and replace both stored credentials together. Reusing the old refresh token fails. Refreshing does not move the original refresh expiration date forward.

If a code or refresh token is invalid, expired, or already used and no current credential remains, restart authorization. Removing the user's workspace membership also prevents continued access.

## Disconnect

Call [Revoke an OAuth grant](/api-reference/oauth/revoke) with the current access or refresh token. Revocation invalidates the grant and its access tokens. Successful revocation returns an empty `200` response, including when the token is absent or unrecognized; do not try to parse JSON from it.

## Compatibility paths

The older paths below invoke the same handlers. Prefer canonical paths for new integrations.

| Compatibility path                      | Canonical path                                               |
| --------------------------------------- | ------------------------------------------------------------ |
| `GET /oauth/raycast/clients/{clientId}` | [GET /oauth/clients/{clientId}](/api-reference/oauth/client) |
| `POST /raycast/oauth/authorize`         | [POST /oauth/authorize](/api-reference/oauth/authorize)      |
| `POST /oauth/raycast/token`             | [POST /oauth/token](/api-reference/oauth/token)              |
| `POST /oauth/raycast/revoke`            | [POST /oauth/revoke](/api-reference/oauth/revoke)            |

Token and revocation endpoints accept JSON or form-encoded bodies. They do not use the developer API's bearer authentication or a client secret. The authorize endpoint accepts JSON and uses the signed-in session. Its request property names are camelCase; token exchange uses OAuth's snake\_case names.


## Related topics

- [Integrations](/integrations/overview.md)
- [Convex](/integrations/convex.md)
- [Revoke an OAuth grant](/api-reference/oauth/revoke.md)
- [Get OAuth client metadata](/api-reference/oauth/client.md)
- [All endpoints](/api-reference/endpoints.md)