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
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.
bearerTokenAuthorizationBearer <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.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
userId*stringIdentifier of the IAM user.
Idempotency-Key?stringOptional; 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.
uuidPassword-reset link dispatched.
application/json- response
Result of dispatching a password-reset link.
userId*stringUser the reset link was issued for.
delivery*"email"Delivery channel.
"email"sentTo*stringMasked destination address, e.g. "e***@acme.io".
sentAt*stringWhen the link was dispatched (ISO).
date-timelinkExpiresAt*stringWhen the reset link expires.
date-timecurl -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"}