# Authorize an OAuth credential

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

An authorization 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.

## 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 to authorize**.
6. Review the external consent screen and approve it.
7. Return to the Credential page after the provider redirects to Constal.

Constal signs the authorization state, stores the PKCE 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 Drivers.

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 authorization again. Open the Credential and choose **Reconnect**. Constal begins a new one-time session; it does not reuse callback codes or PKCE 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).