Documentation / Credentials / Providers

Provider authorization lifecycle

Implement safe browser authorization with signed state, PKCE, callback validation, private refresh state, and recovery.

explanationFor provider authors, security reviewersOwner Constal platform teamVerified 2026-08-20

An interactive CredentialProvider implements authorization.begin and authorization.complete. The platform owns the durable authorization session; provider code owns protocol-specific URL construction and code exchange.

Begin

The platform creates a pending Credential session containing:

  • a signed state value naming the exact Credential and session;
  • an expiry;
  • a PKCE verifier stored only in encrypted session payload;
  • authenticated owner evidence;
  • the exact callback URL.

The provider receives the state, callback, PKCE challenge, and non-secret Credential configuration. It returns one authorization URL. The platform rejects embedded credentials, fragments, a changed state parameter, or an origin outside the provider's declared authorization origins.

Callback

All standard query-based CredentialProviders can share the platform callback. Signed state routes the request to the correct tenant, Credential, and one-time session. The callback does not trust a tenant or Credential supplied in ordinary query input.

Read OAuth callback security for the complete routing and validation sequence.

Complete

The provider receives bounded callback parameters, the original callback URL, PKCE verifier, non-secret configuration, and any encrypted temporary provider state. It exchanges the one-time code through declared egress and returns:

  • access material;
  • optional expiry;
  • optional provider-private lifecycle state.

Constal stores access material as the Credential version. Refresh tokens and equivalent values are encrypted separately and supplied only to later provider lifecycle operations.

Recovery

Choose outcome-unknown when a code or refresh token is single-use and a lost response cannot prove whether the provider consumed it. Do not classify such an exchange as idempotent. An uncertain refresh should surface reconnect rather than risk replaying consumed state.

Use idempotency-key recovery only when the external provider honors a stable idempotency identity or the operation can otherwise prove repeat safety.

Security checklist

  • Require HTTPS origins and exact callback registration.
  • Preserve and verify state.
  • Use PKCE when the external protocol supports it.
  • Exclude codes, verifiers, tokens, and private state from logs and audit payloads.
  • Bound callback fields and reject extras beyond protocol requirements.
  • Verify minted material before activation when an endpoint exists.
  • Destroy or revoke external material when retiring compromised authority.