Integrate

Password reset and email verification

Emails in your own words and HTML; Identise fills in the code and link and checks them.

Your email, Identise's codes

You send these emails through Identise with your own subject and htmlTemplate. In the template, {{code}} becomes a 6-digit code and {{token}} a long link token:

html

<p>Your code: <b>{{code}}</b></p>
<p><a href="https://www.yourapp.com/reset?token={{token}}">Reset your password</a></p>

The template must contain {{code}} or {{token}} (or both), or the request answers 400 HtmlTemplate.Invalid: without either, the user couldn't go on. Up to 200,000 characters.
The subject is required, up to 255 characters.
The email goes out from Identise's sending address, under your app's name. It's sent a moment after the call answers, and retried for about 10 minutes if delivery fails.

Password reset

1
Send the email
POST /v1/oauth/request-password-reset { appId, email, subject, htmlTemplate }. Unknown emails get the same 200, and no email is sent. One email per user per minute: another request within it gets the same 200 and sends nothing. Codes last 15 minutes.
2
Check the code
The user types the code: POST /v1/oauth/verify-password-reset-code { appId, email, code } → { token }. A link already carries a token, so skip this step for links.
3
Set the new password
POST /v1/oauth/reset-password { appId, token, newPassword } → 200. The user is signed out of every session within a few seconds.

The code check needs the email the user typed: a code is only ever checked against that user's latest code, and three wrong codes lock it (403 Verification.TooManyAttempts; request a new one). Without an email the call answers 400 Email.Empty.

Email verification

1
Send the email
POST /v1/oauth/request-email-verification { appId, email, subject, htmlTemplate }, with the same placeholders. Users who are already verified get 200 and no email.
2
Check the code or link
POST /v1/oauth/verify-email { appId, email, codeOrToken }. A 6-digit code needs the email (400 Email.Empty without it; three wrong codes lock it); the long {{token}} from a link works with or without one.

The token's email_verified claim becomes "true" from the next sign-in or refresh.