Skip to Content
Documentation menu

Guides

End users

Only needed when an agent acts for one specific person (a patient, an account holder, a student, a policyholder), not just for your organization. That person agrees to the agent, can approve single actions, and can pause or turn it off at any time.

Skip this page if your agents only work for your organization

Requests without an endUserId are checked against the agent's scope, your rules and your approvers, exactly as before.

The four screens

Each is a hosted page (nothing to build) or a React component from @authentify2026/consent-widget you embed in your own app.

ScreenWhat the person doesHostedComponent
ConsentAllows or doesn’t allow one agent, seeing each action in plain words and what it won’t be able to do.widget_urlAuthentifyConsentWidget
Single-action approvalApproves, denies, or denies and pauses the agent for one escalated action./approveActionApproval
Connected agentsPauses, resumes or turns off each agent./my-agentsConsentManager
ActivitySees everything their agents did or tried for them, and downloads it./my-agentsActivityFeed

Your server starts a consent session with your account key:

POST/api/v1/consent-sessionsaccount key, as Bearer
bash
curl -X POST https://www.authentify.bz/api/v1/consent-sessions \
  -H "Authorization: Bearer $AUTHENTIFY_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "customer_id": "YOUR_CUSTOMER_ID",
    "end_user_id": "customer-42",
    "scope": ["READ_RECORDS", "SCHEDULE_APPOINTMENT"],
    "excluded_scope": ["SHARE_RECORDS"]
  }'

# -> { "session_id": "sess_...", "expires_at": "...", "widget_url": "https://widget.authentify.bz?session=sess_..." }

Send the person widget_url, or embed the widget:

tsx
import { AuthentifyConsentWidget } from '@authentify2026/consent-widget';

<AuthentifyConsentWidget sessionId={sessionId} onApprove={onGranted} onDecline={onDeclined} />

You learn the answer from onApprove / onDecline or the consent_granted / consent_declined webhooks. A grant covers one agent and one person and lasts 30 days. scope must be within the agent's allowed actions.

Step-up verification (optional)

To have the person sign in to your app before the grant is issued, pass require_auth: true and set authRedirectUrl (or onAuthRedirect) on the widget. Your backend confirms with POST /api/v1/consent-sessions/:sessionId/confirm-auth; no consent is granted until it does. If your users sign in with Entra ID, you can instead pass the user's token as subject_token (see token exchange).

2. Name the person on each request

Send endUserId on that person's /api/v2/authorize calls. Without a live consent the request is denied with consent_required; paused gives consent_paused; an action they didn't agree to gives outside_consent_scope. Setting requires_end_user on the agent denies any request that leaves endUserId out (end_user_required).

3. Let the person approve single actions

Turn on end_user_approval for the agent (POST /api/v1/agents/:agentId/update). When a request that named endUserId escalates, the response says endUserCanDecide: true. Your backend asks for a link and sends it to the person (in-app, push, email or SMS):

POST/api/v2/approval-requests/:id/end-user-linkaccount key
bash
curl -X POST https://www.authentify.bz/api/v2/approval-requests/$APPROVAL_REQUEST_ID/end-user-link \
  -H "x-api-key: $AUTHENTIFY_ACCOUNT_KEY"

# -> { "url": "https://www.authentify.bz/approve?approval=euap_...", "expires_at": "...", "end_user_id": "customer-42" }

The page shows the amount, the agent's stated reason and why they're being asked. Their answer resolves the request like an approver's vote and is sealed. The link works once and lasts 30 minutes.

Never give the link to the agent

Whoever holds it can decide the request. That's why /v2/authorize never returns it and agent keys can't request it.

4. Give the person their "my agents" page

From your app's account or settings screen, ask for a link and send the person to it:

POST/api/v2/end-users/:endUserId/portal-linkaccount key
bash
curl -X POST https://www.authentify.bz/api/v2/end-users/customer-42/portal-link \
  -H "x-api-key: $AUTHENTIFY_ACCOUNT_KEY"

# -> { "url": "https://www.authentify.bz/my-agents?portal=...", "expires_at": "...", "end_user_id": "customer-42" }

The link works for 1 hour; ask for a new one each time. If the person's consents are tied to an identity provider, pass { "identity_provider_id": "..." }. To build these screens into your own app instead, embed ConsentManager and ActivityFeed.

Turning an agent back on

People can pause and resume, and they can turn an agent off. They can't turn it back on: only you can, by starting a new consent session that they approve. An agent can never quietly regain access. The same applies when the 30 days run out.

Events

consent_granted, consent_declined, consent_paused, consent_resumed and consent_revoked reach your webhooks. data.detail names the person (end_user_id), the consent_id, the scope and where it happened (source: consent_widget, consent_manager or action_approval).