# 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](/docs/credentials/providers/interaction.md).

## Before you begin {#before-you-begin}

- [Set up the OAuth CredentialProvider](/docs/credentials/providers/setup.md).
- Register the exact [shared callback URL](/docs/credentials/oauth/callback.md) 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 {#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 {#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](/docs/credentials/scoped-bindings.md) before an agent uses the grant.

## Reconnect {#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 {#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 {#next-steps}

Read [OAuth callback security](/docs/credentials/oauth/callback.md) and [Credential lifecycle](/docs/credentials/lifecycle.md).