https://verify.example.com/V1StGXR8_Z5j, instead of a code. The user opens it and is redirected to your
application.
Magic links are available on request. To enable them, contact us with the
subdomain you want to use, the default URL your users land on after opening a link, and the domains you want
to redirect to per verification, if any.
How it works
- You create a verification with a magic link template.
- Prelude sends the SMS with the link.
- The user opens the link. Prelude checks the verification, exactly as a correct code sent to
POST /v2/verification/checkwould. - Prelude redirects the user to your redirect URL. It keeps the URL’s own query parameters as they are, and adds these:
Use
status to choose what to show the user. Sign the user in only from prelude_token.
invalid also covers an account that cannot check verifications at that moment, for example when its
balance is too low, as for POST /v2/verification/check.
Link previews and security scanners (in messaging apps or mail filters) open links before the user does.
Prelude detects common link previews and scanners and redirects them to your redirect URL without checking
the verification and without query parameters. This detection is best effort: treat a success as proof that
the link was opened, not that a person opened it.
Verify the redirect
The redirect goes through the user’s browser, sostatus and verification_id can be changed.
prelude_token is a JWT signed with your
webhook signing key, so your backend can trust it once
it is verified.
The token is signed with PS256 (RSASSA-PSS with SHA-256). Its claims are:
Sign the user in only when:
- the token is valid for your public key, the
PS256algorithm,iss,audandexp. Use a JWT library: it checks all of them; statusin the token issuccess;subis the verification ID you received when you created the verification for this user session;- you have not accepted this
jtior this verification ID before.
Set up your domain
After we register your subdomain, we send you the DNS records to publish:- a
CNAMErecord that points your subdomain to Prelude; - a
CNAMErecord under_acme-challenge.<your subdomain>that lets Prelude issue the TLS certificate; - a
TXTrecord under_cf-custom-hostname.<your subdomain>that proves you own the subdomain. It is optional once the firstCNAMErecord is published, and it lets you set up the domain before you point the subdomain to Prelude.
magic_link_not_configured code.
Create a verification with a magic link
In the Prelude dashboard, in Verify API->Configure, create a template with the Magic Link type. Its message carries the link and no code, in the language of the user. Pass its ID astemplate_id:
Choose the redirect URL per verification
By default, the user lands on the redirect URL set up for your domain. To send this user somewhere else, for example to a recovery page that carries your own token, setredirect_url:
magic_link is accepted only with a magic link template. With any other template, the request returns a 400
error with the magic_link_not_configured code.
The URL must use https, and its domain must be one of your allowed redirect domains, which we set up
with you. The match is exact: allowing example.com does not allow www.example.com, which must be allowed on
its own. Its query must not use status, verification_id or prelude_token, which Prelude adds. Any other
URL returns a 400 error with the invalid_magic_link_redirect_url code, and nothing is sent. This keeps a
stolen API key from sending your users to another site.
A request with a different redirect_url on the same phone number starts a new verification, so the new SMS
carries a link to the new URL. Link previews and security scanners are always redirected to your default
redirect URL, never to the URL of the verification.
The link is valid as long as the verification: once it expires, the user lands on your redirect URL with
status=expired, even if the verification succeeded. Opening the link again after a success and before the
expiry redirects with status=success and does not create a second check.