Describe an authorization request

GET 
/oauth/authorization

What the consent screen shows for an authorize query (§5.2, §10.2): the app, what it asks to see and do (generated from the scope catalog and the version's manifest — never hand-written copy), what it can never do, which events it is notified of, and each workspace the signed-in person administers, with whether the app can be installed there and why not.

The query is checked in this order, and the order decides where an error may go:

1. response_type must be code — else unsupported_response_type, no redirect.
2. The client: unknown, suspended (app or publisher), or a private or test app this person has no workspace to install in → invalid_client, no app details, no redirect.
3. redirect_uri, an exact string of the live version's URIs (test-only URIs, and a version not yet released, only for the publisher's home and test workspaces) → else invalid_redirect_uri, no redirect.
4. Then invalid_scope (asks for more than the version requests) and invalid_request (PKCE other than S256, a malformed code_challenge, no challenge, state over 500 characters) carry meta.redirect_to — only for a public app with a live version.

A signed-in cookie session only: a bearer token (pat_, kat_, a mobile kms_ session) is 403 cookie_session_required; impersonation is 403 impersonation_forbidden; an unverified email is 422 email_unverified. No module gate — the Integrations module and integrations.manage are judged per workspace.

Throttle: none of its own (the 600-a-minute backstop).

Request

Responses

200

The request, described for the consent screen.

401

No session or token, or one that is no longer valid. A request that presented a token gets WWW-Authenticate: Bearer realm="KudosCRM", error="invalid_token" (refresh it); one with no credentials and no session cookie gets the bare challenge.

Response Headers

WWW-Authenticate
Example: Bearer realm="KudosCRM", error="invalid_token"

403

cookie_session_required or impersonation_forbidden (meta.redirect_to is null).

422

The request is refused (steps 1–4 above). meta.redirect_to is the URL the screen may offer as "Return to …", or null; the screen never redirects on its own. Also email_unverified. code is the RFC 6749 one; detail is the admin's sentence for the problem card — what happened to the link and what to do, never a parameter name — and names the app only once its client checked out. The redirect keeps the RFC error_description for your engineers.