1. Docs
  2. API Reference
  3. Admin-trigger a password reset email

Admin-trigger a password reset email

POST/portal/v1/accounts/{accountSlug}/identities/{id}/reset-password

Triggers an admin-initiated password reset for one identity: mints a hashed, time-limited reset token and emails the identity a link into the end-user reset flow. The link opens where the identity's Environment sends its links: the customer's own app when the Environment names one (auth_links_base_url), otherwise Canopy's page. An identity in several Environments needs environment_id to say which. Account-scoped; returns 404 when the identity is not found, 400 when the Environment is missing or not one the identity belongs to, and is rejected for an already-erased identity. Writes an identity.password_reset_triggered audit row and returns a confirmation message.

Authentication

Bearer TokenAuthorization

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

Requires capability identities.manageIdentities

Manage end-user identities across the account. Granted through an administrator role in the Admin Workspace; a valid token without it is refused with 403.

Path Parameters

accountSlugstring Required

The Account's slug. An unknown one answers 404.

idstring Required

Request body

application/json

environment_idstring · uuid Required

The Environment whose link destination the email uses, one the identity belongs to (`400 identity.link_environment_not_member` otherwise). `null` sends Canopy's own page. Required: the identity's Environments are listed in `environment_memberships` on its detail.

Responses

application/json

  • dataMessageResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Errors

When the request can't be completed, the response body includes a stable error code you can branch on, and a correlation_id (also sent as the X-Correlation-Id header). Quote the correlation id when you contact support: it identifies the exact request in Canopy's logs.

403account.capability_requiredForbidden
When it happens

The signed-in user's administrator roles do not grant the capability this endpoint requires.

Remediation

Ask an account administrator to grant a role carrying the capability named in the Authentication section, then retry.

Returned object

MessageResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/portal/v1/accounts/value/identities/value/reset-password" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "00000000-0000-0000-0000-000000000000"
  }'
Response
{
  "data": {
    "message": "string"
  }
}
 Related endpoints
GETList identities in Account
POSTCreate an Account identity
POSTBulk-create Account identities
GETGet directory counts for the Account
GETGet an Account identity
PATCHUpdate an Account identity profile
PATCHSet Account-wide is_active flag
POSTErase an identity (GDPR/CCPA right to be forgotten)
POSTRe-send email verification
POSTRevoke all active sessions for an identity
GETList audit events for an Account identity
POSTAdd an identity to an Environment (create EnvironmentMembership)
POSTBulk-attach EnvironmentMemberships for the Add-from-directory picker
DELETERemove an identity from an Environment (revoke EnvironmentMembership)
 Was this page helpful?

Tell us how we can improve this guide.

Canopy