OAuth2 clients

Registering public and confidential OAuth2 clients, grant types, redirect URIs, and secrets.

Intended audience: Stakeholders, Business analysts, Solution architects, Developers, Testers

Learning outcomes by role

Stakeholders

Understand first-party versus third-party OAuth clients for partnerships.

Business analysts

Capture client registration, redirect URI, and scope requirements.

Solution architects

Secure client secrets, rotation, and network access to token endpoints.

Developers

Testers

Exercise token grants and client revocation scenarios.

Register OAuth2 clients so applications can use authorization code, refresh, and password grants against your Cadence deployment.

Summary for stakeholders

Trust boundaries — Each client ties redirect URIs and grant types to a specific product surface; misconfiguration can leak tokens to the wrong origin.
Secrets — Confidential clients carry secrets; public clients rely on PKCE instead of a shared secret.

Business analysis

Environments — Register separate redirect URI sets per dev/staging/prod; acceptance tests should cover mistyped URIs.
Grants — Document which flows (authorization code, refresh, password) are approved for your org’s policy.

Architecture and integration

Client rows live in PostgreSQL and are consumed by the OAuth2 token and authorization endpoints (cadence.api.oauth2 and related modules).
Network access to /oauth2/* (and /.well-known/openid-configuration) should follow the same TLS and WAF rules as the rest of the API.

Prerequisites

Admin APIs with cadence:system:oauth_clients:read (list) and cadence:system:oauth_clients:write (create)
Known redirect URIs for each environment (dev/staging/prod)

Register a client

Choose a client_id and register redirect_uris for your app (include dev and staging URLs as needed).
Enable authorization_code (and refresh_token if using refresh) in allowed_grant_types.
For server-side apps, set client_type to confidential and supply a client_secret at creation; store the secret securely.
For SPAs, use public clients with PKCE (code_challenge / code_verifier).
Configure your app to discover endpoints from GET /.well-known/openid-configuration at the Cadence API base URL.

Client fields reference

| Field | Type | Meaning | | --------------------- | -------------------------- | -------------------------------------------------------------- | | client_id | string | Unique identifier (e.g. my-spa) | | name | string | Human-readable label | | client_type | public or confidential | Confidential clients require client_secret on token requests | | is_first_party | boolean | Metadata for your UX or policy | | redirect_uris | string[] | Allowed redirect URLs — exact match on /oauth2/authorize | | allowed_grant_types | string[] | e.g. authorization_code, refresh_token, password | | allowed_scopes | string[] | Optional filter; empty means “allow requested scope” | | is_active | boolean | Soft-disable the client |

class OAuth2ClientCreate(BaseModel):
    client_id: str = Field(..., min_length=2, max_length=255)
    name: str
    client_type: str = Field("confidential", pattern="^(public|confidential)$")
    is_first_party: bool = False
    redirect_uris: List[str] = Field(default_factory=list)
    allowed_grant_types: List[str] = Field(default_factory=list)
    allowed_scopes: List[str] = Field(default_factory=list)
    client_secret: Optional[str] = None

Troubleshooting

| Symptom | Cause | Fix | | ------------------------- | ------------------------------------------------------------- | ------------------------------------------------ | | invalid_client on token | Wrong client_id or missing client_secret for confidential | Verify client id and secret | | invalid_redirect_uri | URI not in redirect_uris (must be exact match) | Add the exact URI including trailing slash | | Consent fails | User must be logged in for POST /oauth2/consent/decision | Ensure the user session is active before consent |

Next steps

OAuth2 and BFF integration Authorization code flow, PKCE, consent, and Nuxt BFF patterns.

API keys Automation credentials with cdk_ prefix and permission scopes.