Verify email (OTP)
curl --request POST \
--url https://api.example.com/api/v1/auth/verify-emailimport requests
url = "https://api.example.com/api/v1/auth/verify-email"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/auth/verify-email', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/auth/verify-email",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/auth/verify-email"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/auth/verify-email")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/auth/verify-email")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyAuth
Verify email (OTP)
Confirm a 6-digit verification code and receive access + refresh tokens.
POST
/
api
/
v1
/
auth
/
verify-email
Verify email (OTP)
curl --request POST \
--url https://api.example.com/api/v1/auth/verify-emailimport requests
url = "https://api.example.com/api/v1/auth/verify-email"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/auth/verify-email', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/auth/verify-email",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/auth/verify-email"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/auth/verify-email")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/auth/verify-email")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyOverview
Verifies the 6-digit OTP that was sent to the user’s email during registration (or viaPOST /resend-verify-email). On success:
- The OTP row is marked consumed.
users.emailVerifiedis set totrue.- A new session is minted — access token (RS256 JWT, 15-min TTL) + refresh token (256-bit opaque, 30-day TTL, single-use rotating).
attemptsUsed and return 401 INVALID_CODE. After 5 attempts the row is dead and further calls return 401 CODE_EXPIRED; the client must request a fresh code.
A valid, live code is always required, including for an account that is already verified: this endpoint takes no password, so the code is the only proof of ownership. A repeated call with a consumed code returns CODE_EXPIRED; the client should send the user to /auth/login instead.
Authentication
None required — this endpoint is part of the login sequence.Path parameters
None.Query parameters
None.Request body
| Field | Type | Required | Allowed values | Example |
|---|---|---|---|---|
email | string | yes | RFC 5322 valid, lowercased server-side | alice@example.com |
code | string | yes | Exactly 6 digits | 482301 |
Example payload
{
"email": "alice@example.com",
"code": "482301"
}
Response — 200 OK
| Field | Type | Notes |
|---|---|---|
accessToken | string | RS256 JWT, 15-min TTL. |
refreshToken | string | 256-bit opaque, 30-day TTL, single-use rotating. |
user | object | See below. |
User object
| Field | Type | Allowed values | Example |
|---|---|---|---|
id | string | 24-char Mongo ObjectId | 6a22f1897f96f4bd18ab7168 |
email | string | lowercased | alice@example.com |
firstName | string | null | null until collected at signup | Alice |
lastName | string | null | null until collected at signup | Andersson |
avatarUrl | string | null | Public CDN URL of the profile photo, or null | null |
emailVerified | boolean | Always true on this response | true |
onboardingStep | string | normalized lowercase of OnboardingStatus | in_progress |
tenancyStatus | string | normalized lowercase | not_submitted |
subscriptionStatus | string | normalized lowercase | free_launch |
Example response
{
"accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "v8q3xZ0p6rW7sT4uV1nB2cX9yY8mK5jL6hG7fD3eA0c",
"user": {
"id": "6a22f1897f96f4bd18ab7168",
"email": "alice@example.com",
"firstName": "Alice",
"lastName": "Andersson",
"avatarUrl": null,
"emailVerified": true, // literal: true
"onboardingStep": "in_progress", // enum: "in_progress" | "complete"
"tenancyStatus": "not_submitted", // enum: "not_submitted" | "pending" | "approved" | "rejected"
"subscriptionStatus": "free_launch" // enum: "none" | "trialing" | "active" | "past_due" | "cancelled" | "free_launch"
}
}
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | Email malformed, or code is not exactly 6 digits. |
| 401 | INVALID_CODE | Wrong digits. attemptsUsed was bumped; you have at most 5 wrong tries before the row dies. |
| 401 | CODE_EXPIRED | No live OTP for this email — either it expired (5-min TTL), it was already consumed, or the attempt cap was hit. Request a fresh code via /resend-verify-email. |
Example error — 401 INVALID_CODE
{
"type": "https://api.swappr.co.uk/errors/invalid-code",
"title": "Verification code incorrect",
"status": 401,
"code": "INVALID_CODE",
"detail": "Verification code is incorrect",
"instance": "/api/v1/auth/verify-email",
"requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2"
}
Side effects
- Marks the OTP row consumed (
consumedAt = now). - Sets
users.emailVerified = true. - Inserts a
refresh_tokensrow keyed by the new session id.
See also
- Register (email + password) — the step that issues the code.
- Resend verification email — get a fresh code after the TTL or attempt cap.
curl
curl -X POST https://api.swappr.co.uk/api/v1/auth/verify-email \
-H "Content-Type: application/json" \
-d '{
"email": "alice@example.com",
"code": "482301"
}'