Skip to main content
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 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 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 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.
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 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. 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.