Consent Management

When a user authenticates through the OIDC flow for the first time, YorAuth displays a consent screen listing the scopes (permissions) that the client application is requesting. The user must explicitly approve these scopes before an authorization code is issued. Subsequent logins skip the consent screen if the user previously granted all of the requested scopes.

How Consent Works

Consent is stored in the oidc_consent_grants table, keyed by user_id and oidc_client_id. A consent grant records which scopes were approved and when. Grants are considered active until they are revoked.

Authorization Request
        │
        ▼
User authenticates (login / MFA)
        │
        ▼
Check OidcConsentGrant for this user + client
        │
        ├── Grant exists and covers all requested scopes?
        │   └── YES → Skip consent screen → Issue auth code → Redirect
        │
        └── No valid grant?
            └── Show consent screen
                    │
                    ├── User approves → Create/update grant → Issue auth code → Redirect
                    │
                    └── User denies → Redirect with error=access_denied

Consent Screen

The consent screen is part of YorAuth's hosted login flow. It displays:

• The client's name and branding (logo, colors)
• A description of each requested scope
• The authenticated user's email address
• "Allow" and "Deny" buttons

The scope descriptions shown to users are:

Skipping Consent for Returning Users

After a user approves consent, YorAuth creates a OidcConsentGrant record. On the next authorization request, the flow checks whether the grant's scopes array is a superset of the currently requested scopes. If all requested scopes are already covered, the consent screen is bypassed automatically.

Requested: ["openid", "email"]
Granted:   ["openid", "profile", "email", "offline_access"]

Result: Consent skipped — granted scopes are a superset of requested

Requested: ["openid", "profile", "email", "offline_access"]
Granted:   ["openid", "email"]

Result: Consent screen shown — "profile" and "offline_access" not yet granted

When a user approves consent, the grant is updated using updateOrCreate — the new scopes replace the previous grant entirely. This ensures the grant always reflects the most recently approved scope set.

User Denial

If the user clicks "Deny" on the consent screen, YorAuth redirects back to the client's redirect_uri with an OAuth error:

https://yourapp.com/auth/callback
  ?error=access_denied
  &error_description=The+user+denied+the+authorization+request.
  &state=your-state-value

No authorization code is issued. The flow session is cleared from YorAuth's side. Your application should handle this error gracefully — typically by showing a message explaining that access was denied and offering to try again.

Revoking Consent

Users can withdraw consent for a specific OIDC client. This sets the revoked_at timestamp on the grant. Revoked grants are excluded from the consent-skip check, so the user will be shown the consent screen again on their next login.

Consent revocation is available through the V1 API user profile endpoint:

DELETE /api/v1/applications/{applicationId}/users/{userId}/consent

This endpoint requires JWT authentication and user-ownership verification (auth.user-owner middleware). It implements the GDPR Article 7(3) right to withdraw consent.

Consent Grant Lifecycle

Created at:  First approval via consent screen
Updated at:  Re-approval after requesting new or additional scopes
Revoked at:  User withdraws consent via DELETE /users/{userId}/consent

A grant is considered active when revoked_at is null. Only active grants are checked in the consent-skip logic.

For Application Developers

Pre-authorizing Consent

If your application always requests the same scopes and you want to avoid the consent screen entirely for your users, you can pre-authorize consent programmatically after user creation using the V1 API.

There is no dedicated "pre-authorize" endpoint — consent is created by the user through the hosted flow. If you need to remove the consent step for a managed deployment (e.g., a first-party application where user consent is implicit), contact YorAuth support to discuss options for your use case.

Requesting Additional Scopes

If your application later needs access to additional scopes (e.g., you initially requested only openid email and now also need offline_access), simply include the new scopes in the next authorization request. The user will be shown the consent screen again because the existing grant does not cover the new scope.

// Previously requested: openid email
// Now requesting: openid email offline_access

const authUrl = new URL('https://api.yorauth.com/oidc/authorize');
authUrl.searchParams.set('scope', 'openid email offline_access');
// ... other params
window.location.href = authUrl.toString();

Checking Consent Status

There is no public endpoint to query a user's current consent grants. Consent state is internal to YorAuth and managed through the hosted flow. If you need to know whether a user has granted consent, attempt an authorization request — if consent has already been granted, the flow will complete without showing a consent screen.