Request a password reset token

Request a single-use password reset token for an identity. Your app then sends the token to the identity, e.g. as a link in an email: JSONPad never sends email itself. See password reset and email verification for the whole flow.

The API token needs the reset-password permission for the identity's group. A token can be requested for each identity once a minute, and requesting a new token replaces the previous one. Tokens expire after the identity group's token lifetime.

Unless the identity group delivers tokens to a webhook, this returns the token. Anyone who can call it with your API token could take over any identity in the group, so only call it from a server, with an API token that never leaves it. Requests from a browser (with an Origin header) are refused.

POST https://api.jsonpad.io/identities/password-reset

Example

1234567

curl https://api.jsonpad.io/identities/password-reset \
  -H "Content-Type: application/json" \
  -H "x-api-token: <YOUR TOKEN>" \
  -d '{
        "group": "sample-group",
        "email": "identity@example.com"
      }'

Parameters

No parameters

Request headers

required
x-api-tokenstringYour API token.

Request body

{group: "sample-group"
email: "identity@example.com"
}

optional
groupstringThe identity group. Leave this out for identities with no group.
optional
identityIdstringThe identity's id. Exactly one of identityId, name and email is required.
optional
namestringThe identity's name.
optional
emailstringThe identity's email address (ignoring case).

Response body

200 OK

The token and the identity it's for, so your server knows where to send it. If no activated, unlocked identity matches, resetToken, expiresAt and identity are all null.

{resetToken: "mprJNQxDHeU1eUgCZaoAsnUtf6Z9Q6EZu80RpsW_cHM"
expiresAt: "2026-09-18T20:32:09.218Z"
identity: {id: "57d6b2cb-7a02-4bff-b9ee-616fb5c2073f"
createdAt: "2026-09-18T20:32:09.218Z"
updatedAt: "2026-09-18T20:32:09.218Z"
name: "Sample Identity"
displayName: "Sample Display Name"
email: "identity@example.com"
emailVerified: false
hasPassword: true
tags: [0: "my-app"
]
group: "sample-group"
lastLoginAt: "2026-09-18T20:32:09.218Z"
activated: true
}
}

Don't tell the person using your app whether an identity was found: always show the same message, such as "if there's an account for that address, we've sent an email".

202 Accepted

If the identity group delivers tokens to a webhook, the token is sent there instead, and the response is always the same, whether or not an identity was found.

{delivery: "webhook"
}

Response headers

No response headers

2026-09-17