BuildUsers

Registered Users

The identity Agent Handler attaches every credential and tool call to.

A Registered User is the unit of isolation in Agent Handler. Every credential, every Link session, every tool call, and every audit record is scoped to one. There’s one Registered User per end user of your product - your customer’s user, an employee on your team, or your own dev account.

Two IDs are central:

  • origin_user_id - your stable identifier for the user in your own database. Required.
  • origin_company_id - your stable identifier for the user’s parent tenant, in your own database. Optional; required for shared-credential Tool Packs.

Both are strings under your control. Use whatever you already use internally - UUIDs, integers, email addresses. They’re the join key when you query Agent Handler back from your app.

Creating a Registered User

Create the Registered User the moment you onboard a new user in your product. The call is idempotent on origin_user_id - if the Registered User already exists, you get the existing one back, not a duplicate.

$curl -X POST https://ah-api.merge.dev/api/v1/registered-users \
>  -H "Authorization: Bearer $MERGE_AGENT_HANDLER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "origin_user_id": "user_a3f9b2",
>    "origin_user_name": "Alice Chen",
>    "origin_user_email": "[email protected]",
>    "shared_credential_group": {
>      "origin_company_id": "company_acme",
>      "origin_company_name": "Acme Inc."
>    }
>  }'
1{
2  "registered_user_id": "f9813dd5-e70b-484c-91d8-00acd6065b07"
3}

Store registered_user_id against your user record. You’ll need it on every MCP call.

Multi-tenancy patterns

The shared_credential_group field expresses “these users belong to one tenant” - useful in B2B products where one customer has multiple users. Pass the same origin_company_id for every user from the same customer. It powers two things: shared-credential Tool Packs (one Slack workspace per tenant; every user inherits the credentials) and dashboard filtering (logs, alerts, and tool calls by Company).

The optional custom_groupings field attaches arbitrary key-value pairs to a Registered User - region: "EU", tier: "enterprise". These power Groups, which slice users dynamically by attribute.

Lifecycle

OperationEffect
CreateRegistered User exists with no credentials. Tool calls fail until they authenticate.
UpdateUpdating origin_user_name, email, or groupings is non-destructive. Updating origin_user_id is not allowed.
Authenticate a ConnectorThrough Link or Magic Link. One credential per (Registered User × Connector) pair.
Revoke a credentialThe user’s Connector stops being callable. They can re-authenticate to restore.
Deactivate the userAll credentials are revoked. Tool calls fail closed. In-flight calls complete; new ones don’t start.
Delete the userHard delete. Credentials, tool-call history, and audit records associated with the user are retained for the org’s retention period (default 90 days), then purged.

For dashboard-driven test users (no origin_user_id of your own to attach yet), see the Registered Users page → Test environment.

Common errors

ErrorWhat it meansWhat to do
400 origin_user_id_requiredYou omitted origin_user_id in the create body.Pass it.
409 origin_user_id_takenA Registered User with that origin_user_id already exists in this environment.The call should be idempotent and return the existing user. If you’re seeing 409, you’re hitting a different environment than the one the original was created in (check test vs production).
404 registered_user_not_foundThe MCP URL contains an ID that doesn’t resolve.Check the ID; check you’re using the right environment’s API key.
400 invalid_company_for_shared_scopeTool Pack uses shared scope but the Registered User has no origin_company_id.Add the Company ID to the Registered User, or switch the pack to individual scope.

When the user is gone

If a user offboards from your product, deactivate the Registered User (don’t delete) so the audit log remains intact. Deactivation revokes credentials immediately; the user’s history stays queryable.

$curl -X PATCH https://ah-api.merge.dev/api/v1/registered-users/$REGISTERED_USER_ID \
>  -H "Authorization: Bearer $MERGE_AGENT_HANDLER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{ "is_active": false }'

For full deletion (data subject requests, GDPR), use DELETE on the same endpoint. Deletion is irreversible.

Next

Group Registered Users by tenant or attribute with Companies and Groups.