Skip to main content

OAuth Clients

The console and API expose an OAuth client registry and authorization-code endpoints with PKCE. They are useful for inspecting the intended delegated authorization shape, but they do not currently form a supported end-to-end public API authentication contract.

:::danger Current support boundary

Tokens returned by /v1/oauth/token are not accepted by the main public API bearer-authentication path. Do not ship a production integration on this flow until Keeptrusts publishes a supported OAuth bearer contract. For unattended service automation, use a scoped API token.

:::

Register a client​

Open API Tokens → OAuth Clients, open Actions, and select Register OAuth client. Provide:

  • a recognizable application name;
  • every exact redirect URI; and
  • the scopes you intend the application to request.

The API registers a public PKCE client and returns a client ID. It does not issue a client secret. Copy the client ID and keep the registered metadata in the integration's design record.

The current console success view still contains client-secret copy, but the API response has no client_secret field. A blank value in that view is not a credential.

Registered scopes are currently stored and displayed as client metadata, but the authorization handler does not enforce that a requested scope is a subset of the registered values. Do not treat the registry selection as an authorization boundary.

Redirect URI rules​

Register an HTTPS callback. The current validator also accepts an HTTP local-development URI string that begins with http://localhost; keep that exception on an actual localhost host. The callback must match the registered URI exactly, including:

  • scheme;
  • hostname;
  • port;
  • path; and
  • any environment-specific distinction.

Do not add broad or unused callbacks. Register development, staging, and production URIs only when each is an intentional deployment target. Prefer separate clients when the environments need separate ownership or revocation.

Understand the current PKCE mechanics​

The current endpoints implement these mechanics:

  1. The caller creates a high-entropy code verifier and its S256 challenge.
  2. An authenticated Keeptrusts user calls /v1/oauth/authorize with the client, redirect URI, scope, challenge, and state.
  3. The API returns JSON containing redirect_uri as the full callback URL with the code and optional state appended, plus the one-time authorization code as a separate field; it does not perform the browser redirect.
  4. The caller validates state, moves the browser to the returned URI, and exchanges the code and original verifier at /v1/oauth/token.
  5. The caller stops at the current support boundary: the resulting access token is not a supported public API bearer credential.

There is no separate consent screen or approval step in the current authorize handler. Validate state in the client to bind the callback to the initiating browser session. Never log authorization codes, code verifiers, or token artifacts.

Use the discovery and endpoint details published by the active Keeptrusts environment rather than hard-coding an endpoint copied from another region or deployment.

Least-privilege review​

For each client, record:

  • owner and support contact;
  • business purpose;
  • environments and redirect URIs;
  • intended scopes;
  • client replacement review date; and
  • revocation plan.

The console registry supports search by name, client ID, scope, and redirect URI. Use it during periodic review to find unexpected callbacks or scopes.

Replace a client registration​

There is no client secret to rotate. To change client identity or isolate an environment, use a controlled registration replacement:

  1. Register a new client with the exact callbacks and intended scopes.
  2. Update the application to use the new client ID.
  3. Exercise the PKCE mechanics in a non-production environment while observing the support boundary above.
  4. Deactivate the old client after every registered environment is accounted for.
  5. Revoke known old access and refresh token artifacts separately.
  6. Review Trail.

Do not deactivate the old client before every environment has a reviewed replacement plan.

Deactivate a client​

The console delete action deactivates the client rather than removing its record. Deactivation blocks new authorization requests for that client, but it does not revoke existing token records. Revoke each known access or refresh token separately at /v1/oauth/revoke.

Before deactivation:

  • identify every environment using the client ID;
  • inventory and revoke known token artifacts;
  • preserve required audit evidence;
  • schedule and communicate the change; and
  • verify the replacement registration where continued testing is required.

Troubleshooting​

FailureCheck
Redirect mismatchExact registered URI, including scheme, port, path, and trailing slash
Invalid clientClient ID, active state, and environment
PKCE failureSame verifier used for the challenge and code exchange; S256 challenge method
Authorize call does not redirectExpected current behavior: read the JSON redirect_uri and code; the API does not issue an HTTP redirect
Issued token receives 401 on the public APIExpected current boundary: OAuth token artifacts are not accepted by the main public bearer path
Scope appears accepted unexpectedlyRegistered scope values are not currently enforced as the authorize-request ceiling
Repeated callback or state errorOne-time code use, state validation, session storage, and clock

Next steps​