Identity & Access Management

Preview — pending review

This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.

Send a password-reset link to a user

POST
/scopes/{scopeId}/iam/users/{userId}/passwords/actions/reset

Sends the selected user a password-reset link by email (the "Reset password" action in the detail header). The user's current password stays valid until they complete the reset through the link; no session is terminated by this command. The result records where the link was sent (masked address) and when it expires. Validation: userId must exist and be visible in scopeId (404 via ErrNotFound); the user's current state must permit a reset — SSO-managed users with no local password (lastPasswordChange null, local sign-in disabled) and INVITED users who have never set a password are rejected with 409 CONFLICT; the caller must hold owner|admin on the scope. Async & state: Synchronous — returns 200 with the reset-dispatch result; the email itself is delivered out of band. No user state changes until the link is used, at which point lastPasswordChange updates and a resource.updated SSE frame (kind iam.user, patch on lastPasswordChange) is emitted. Errors: 401 unauthenticated; 403 when the caller lacks owner|admin on the scope; 404 when scopeId/userId is unknown; 409 when the user is SSO-managed or otherwise not eligible for a local password reset; 429 when reset emails are rate-limited; 500 on dispatch failure. Idempotency/Concurrency: Idempotency-Key is optional (recommended) because the UI can retry; replaying the same key returns the original result without sending a duplicate email. Issuing a new reset link later invalidates previously issued unexpired links.

Authorization

bearerToken
headerAuthorizationBearer <token>

An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

userId*string

Identifier of the IAM user.

Header Parameters

Idempotency-Key?string

Optional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.

Formatuuid

Response Body

Password-reset link dispatched.

application/json
  1. response

Result of dispatching a password-reset link.

userId*string

User the reset link was issued for.

delivery*"email"

Delivery channel.

Value in"email"
sentTo*string

Masked destination address, e.g. "e***@acme.io".

sentAt*string

When the link was dispatched (ISO).

Formatdate-time
linkExpiresAt*string

When the reset link expires.

Formatdate-time
curl -X POST "https://example.com/scopes/string/iam/users/string/passwords/actions/reset"
{  "userId": "string",  "delivery": "email",  "sentTo": "string",  "sentAt": "2019-08-24T14:15:22Z",  "linkExpiresAt": "2019-08-24T14:15:22Z"}