User security administration API reference

When a member loses a device, leaves the team, or reports a compromised account, a security operator needs to act on that member's account directly. The member cannot always sign in to fix it themselves. These endpoints let an authorized operator inspect a member's security posture and revoke access on their behalf. An operator can read which sign-in protections and sessions are active, sign the member out of one browser or all of them, reset multi-factor authentication, and start a password reset.

Each endpoint acts on a single member of your authenticated organization. They administer account access, not wallet signing: they cover sign-in sessions, multi-factor authentication, and password recovery, not the PIN or recovery-code controls that gate wallet operations. A member who manages their own security through the Console uses the controls described in Account security; these endpoints are the operator-facing counterpart.

For authentication and base URL setup, see Getting started. The active organization context bounds every call, as described in Organization and system scope.

Endpoints

Each endpoint uses the single-resource envelope with data and links.self. The read endpoint returns the member's security state; each mutation returns a confirmation object.

Access scope

Every endpoint here requires the system user-security-management permission for the active system. A caller without that role cannot read or change another member's security, even within their own organization.

Each call is scoped to the authenticated organization. The target member, session, multi-factor record, or email must belong to a member of that organization, or the endpoint reports the target as not found rather than acting across organizations. The userId path parameter is the member's internal platform user ID; the sessionId parameter is the ID returned by the security read.

Read a member's security state

GET /api/v2/users/{userId}/security returns whether the member has multi-factor and wallet protections enabled, along with the sessions currently signed in to your organization.

curl --globoff "https://your-platform.example.com/api/v2/users/usr_01HXYZ/security" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "twoFactorEnabled": true,
    "walletPincodeEnabled": true,
    "walletTwoFactorEnabled": false,
    "walletSecretCodesConfirmed": true,
    "sessions": [
      {
        "id": "ses_01HXYZ",
        "userId": "usr_01HXYZ",
        "ipAddress": "203.0.113.10",
        "userAgent": "Mozilla/5.0",
        "createdAt": "2026-06-20T09:12:00.000Z",
        "updatedAt": "2026-06-24T14:03:00.000Z",
        "expiresAt": "2026-07-04T09:12:00.000Z"
      }
    ]
  },
  "links": {
    "self": "/v2/users/usr_01HXYZ/security"
  }
}

The sessions array lists only sessions that are still active in your organization and have not expired. Each session reports its origin and timestamps so you can recognize an unexpected location or device, but never the session token itself. Use a listed id with the single-session revoke endpoint below.

The four boolean fields describe the member's protections:

If no member with that ID belongs to the organization, the endpoint returns 404 with error code DALP-0426. Verify the user ID and confirm the member belongs to the organization your session is scoped to.

Revoke one session

DELETE /api/v2/sessions/{sessionId} signs the member out of a single browser session. Read the member's security state first to find the session ID, then revoke the one you no longer want to trust.

curl --globoff -X DELETE "https://your-platform.example.com/api/v2/sessions/ses_01HXYZ" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "success": true
  },
  "links": {
    "self": "/v2/sessions/ses_01HXYZ"
  }
}

The endpoint revokes the session only when it belongs to a member of your organization. If the session ID does not match a session in your organization, the endpoint returns 404 with error code DALP-0426.

Revoke every session for a member

DELETE /api/v2/users/{userId}/sessions signs the member out of every active session in your organization in one call. Use it when a member's account may be compromised and you want to end all access at once rather than revoking sessions one at a time.

curl --globoff -X DELETE "https://your-platform.example.com/api/v2/users/usr_01HXYZ/sessions" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "success": true
  },
  "links": {
    "self": "/v2/users/usr_01HXYZ/sessions"
  }
}

The endpoint clears the member's sessions for the active organization only. A member signed in to a different organization keeps those sessions. If no member with that ID belongs to the organization, the endpoint returns 404 with error code DALP-0426.

Reset multi-factor authentication

DELETE /api/v2/users/{userId}/multi-factor-authentication removes the member's authenticator-app enrollment and turns off multi-factor sign-in for their account. Use it when a member loses their authenticator device and cannot complete the sign-in step. After the reset, the member signs in with their password and can enroll a new authenticator from their own account security page.

curl --globoff -X DELETE "https://your-platform.example.com/api/v2/users/usr_01HXYZ/multi-factor-authentication" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "success": true
  },
  "links": {
    "self": "/v2/users/usr_01HXYZ/multi-factor-authentication"
  }
}

This reset clears account multi-factor authentication only. It does not change the member's wallet PIN, wallet authenticator, or recovery codes, which protect wallet-sensitive operations separately. If no member with that ID belongs to the organization, the endpoint returns 404 with error code DALP-0429.

Trigger a password reset

POST /api/v2/users/{userId}/password-reset-requests starts a password reset for the member so they can choose a new password themselves. The endpoint never sets a password directly; it hands the request to the platform's reset flow, which emails a reset link to the address on the member's account.

curl --globoff -X POST "https://your-platform.example.com/api/v2/users/usr_01HXYZ/password-reset-requests" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "success": true
  },
  "links": {
    "self": "/v2/users/usr_01HXYZ/password-reset-requests"
  }
}

A success response confirms the platform accepted the reset request and queued the email to the address on the member's account. Delivery then depends on the deployment's email configuration. Two conditions report a problem instead of accepting the request:

• No member with that ID belongs to the organization. The endpoint returns 404 with error code DALP-0428.
• The member has no email address on file, so there is nowhere to send the reset link. The endpoint returns 400 with error code DALP-0423. Add an email to the member's account before triggering a reset.

Errors and retry behavior

Every endpoint on this surface returns the same envelope on failure: a stable error code, an HTTP status, and a message that never echoes the target member's email, session metadata, or other personal data. Most failures here are terminal client errors: the same request fails the same way until you change the request or the organization's state, so retrying an unchanged request does not help. The one retryable case is marked below.

The permission check runs first, in shared middleware, so an unauthorized caller is rejected on authority before any member data is read or any session is touched. A 403 therefore tells you the calling account is missing the role, not that the target is missing or malformed.

A successful response confirms only that the platform accepted the request: a password-reset success means the reset email was queued, not delivered or completed, so treat the member's own reset action as the point where access actually changes.

For the full catalog of platform error codes, see the Platform API error reference. For shared retry and error-envelope conventions, see Error handling.

When to use these endpoints

Reach for this surface when you need to act on another member's account access:

• Read a member's MFA status and sessions during a security review or incident.
• Revoke a single suspicious session, or revoke every session when an account may be compromised.
• Reset multi-factor authentication for a member who lost their authenticator device.
• Start a password reset for a member who cannot sign in.

To read aggregate counts of members instead of one member's security state, see User statistics. To resolve a single member from a national ID, wallet, or user ID, see User lookup. For the self-service controls a member manages in the Console, see Account security.