AI and agents
User claim flow
What users and agents should expect during delegated agent approval.
The claim ceremony keeps a human in control of the first connection between an external agent and a Whagons tenant.
Agent-side sequence
- Ask the user which Whagons email address should approve access.
- Register a
service_authidentity with only the necessary scopes. - Show the six-digit code exactly as returned.
- Open or present
verification_uri_complete. - Explain that the agent will act with the user's current Whagons permissions.
- Poll no faster than the returned interval.
- Stop polling on expiry, rejection, or another terminal error.
- Store the resulting credential in a secret store, never in conversation history or logs.
User-side sequence
- Open the verification link supplied by the agent.
- Sign in to Whagons with the same email address the agent used as
login_hint. - Compare the six-digit code on the page with the code shown by the agent.
- Select the tenant if the account belongs to more than one.
- Review the agent's purpose and requested access.
- Choose Approve agent only when the agent and request are expected.
After approval, the page confirms that the agent may request an access token for the selected tenant.
What approval means
Approval does not create a new Whagons user and does not grant tenant-wide administrator access. The agent is linked to the approving user and selected tenant. Every API operation remains subject to:
- the issued agent scopes;
- the user's current role permissions;
- team membership;
- workspace and task visibility;
- field, status-transition, approval, and lifecycle policy.
Common errors
| Message or code | Cause | Recovery |
|---|---|---|
authorization_pending | The user has not completed approval. | Wait for the advertised interval and poll again. |
Claim expired | The ten-minute claim window ended. | Start a new identity registration. |
Invalid code | The entered code does not match the claim. | Compare the six digits and retry before expiry. |
This claim was started for … | The signed-in email differs from login_hint. | Sign in with the intended account or restart with the correct email. |
Choose a tenant before claiming this agent | The user belongs to multiple matching tenants. | Select one tenant on the approval screen. |
No Whagons tenant user matched this claim | No active user matches the email and tenant. | Verify membership or ask a tenant admin. |
invalid_grant | A token, assertion, claim, or registration is invalid or no longer active. | Stop retrying the same value and restart discovery or registration. |
Safety guidance for users
- Do not approve an agent you did not initiate.
- Verify the code through the original agent conversation.
- Choose the narrowest tenant and scope set.
- Revoke agent access when the tool is no longer used.
- Report unexpected agent activity to a tenant administrator.
For request examples after approval, see Agent API access.