Authorize an OAuth credential

Create a durable per-user Credential through a provider-managed browser authorization flow.

An OAuth Credential represents one external grant. The provider is installed once for the tenant-owned application; each completed user grant becomes a separate Credential with isolated lifecycle state. OAuth is one recipe implemented on the generic provider interaction lifecycle.

Before you begin

• Set up the OAuth CredentialProvider.
• Register the exact shared callback URL in the external application.
• Decide which principal or customer will own the resulting assignment.
• Confirm the requested permissions are no broader than the agent's intended operations.

Steps

1. Open Credentials and select Create credential.
2. Choose the installed OAuth provider.
3. Enter a recognizable name.
4. Complete only the required provider fields. Optional parameters remain under Optional settings.
5. Select Continue.
6. Review the external consent screen and approve it.
7. Return to the Credential page after the provider redirects to Constal.

Constal signs the interaction state, stores the proof verifier and provider-private state in the pending Credential session, consumes the callback once, and verifies the resulting material before activation.

Verify

The Credential should become Active. The access token is stored as Credential material. Refresh tokens and similar lifecycle values remain encrypted provider-private state and are never exposed to consuming integrations.

Create the appropriate principal- or customer-scoped binding before an agent uses the grant.

Reconnect

If refresh becomes uncertain, expires, or is rejected, the Credential enters a state that requires connection again. Open the Credential and choose Reconnect. Constal begins a new one-time interaction; it does not reuse callback codes or proof verifiers.

Troubleshooting

• Authorization denied: begin again and approve the required permissions.
• State invalid or expired: restart from the Credential page; do not replay the callback URL.
• Redirect mismatch: register the exact callback displayed in provider setup.
• Grant succeeds but the agent cannot use it: verify the scoped binding and credential:use Policy.

Next steps

Read OAuth callback security and Credential lifecycle.