Login (email + password)
curl --request POST \
--url https://api.example.com/api/v1/auth/loginimport requests
url = "https://api.example.com/api/v1/auth/login"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/auth/login', 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/login",
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/login"
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/login")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/auth/login")
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
Login (email + password)
Exchanges email + password for access + refresh tokens
POST
/
api
/
v1
/
auth
/
login
Login (email + password)
curl --request POST \
--url https://api.example.com/api/v1/auth/loginimport requests
url = "https://api.example.com/api/v1/auth/login"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/auth/login', 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/login",
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/login"
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/login")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/auth/login")
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
Logs in an existing user with email + password and returns an access token (RS256 JWT, 15-min TTL) plus a refresh token (256-bit opaque, 30-day TTL, single-use rotating). The user must have verified their email (emailVerified: true); if not, the response is 403 STATE_CONFLICT with detail: "Email not verified".
Authentication
None required — this is the endpoint that grants authentication.Path parameters
None.Query parameters
None.Request body
| Field | Type | Required | Allowed values | Example |
|---|---|---|---|---|
email | string | yes | RFC 5322 valid, lowercased server-side, 5..254 chars | alice@example.com |
password | string | yes | 1..200 chars (we do not constrain composition beyond minimum length; argon2id absorbs the cost) | correct horse battery staple |
Example payload
{
"email": "alice@example.com",
"password": "correct horse battery staple"
}
Response — 200 OK
| Field | Type | Notes | Example |
|---|---|---|---|
accessToken | string | RS256 JWT, 15-min TTL. Pass in Authorization: Bearer <accessToken>. | eyJhbGciOiJSUzI1NiIs... |
refreshToken | string | 256-bit opaque token, base64url, 30-day TTL. Single-use; rotates on every /auth/refresh. | v8q3..._43-chars-total |
user | object | See User object. |
User object
This is a lightweight summary for rendering the Account header immediately after login. For the full profile (includingdateOfBirth and bio), call GET /users/me.
| Field | Type | Allowed values | Example |
|---|---|---|---|
id | string | 24-char Mongo ObjectId | 6a22f1897f96f4bd18ab7168 |
email | string | lowercased | alice@example.com |
firstName | string | null | 1..100 chars; null until collected at signup | Alice |
lastName | string | null | 1..100 chars; null until collected at signup | Andersson |
avatarUrl | string | null | Public CDN URL of the profile photo, or null | null |
onboardingStep | string | Lowercased status: in_progress | complete | in_progress |
tenancyStatus | string | Lowercased: not_submitted | pending | approved | rejected | not_submitted |
subscriptionStatus | string | Lowercased: none | trialing | active | past_due | cancelled | free_launch | expired | none |
The status fields (
onboardingStep, tenancyStatus, subscriptionStatus) are returned lowercased strings in this payload. GET /users/me returns the canonical UPPERCASE enum values for onboardingStatus/tenancyStatus.Example response
{
"accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "v8q3xZ0p6rW7sT4uV1nB2cX9yY8mK5jL6hG7fD3eA0c",
"user": {
"id": "6a22f1897f96f4bd18ab7168",
"email": "alice@example.com",
"firstName": "Alice",
"lastName": "Andersson",
"avatarUrl": null,
"onboardingStep": "in_progress", // "in_progress" | "complete"
"tenancyStatus": "not_submitted", // "not_submitted" | "pending" | "approved" | "rejected"
"subscriptionStatus": "none" // "none" | "trialing" | "active" | "past_due" | "cancelled" | "free_launch" | "expired"
}
}
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | Email is malformed, password is missing, etc. |
| 401 | UNAUTHENTICATED | Email + password combination is wrong (we do NOT distinguish between unknown email and wrong password — prevents user enumeration). |
| 403 | STATE_CONFLICT | Email not verified yet. |
| 403 | ACCOUNT_BANNED | User is banned. |
| 403 | ACCOUNT_PENDING_DELETION | Credentials are correct, but the account was soft-deleted and is still inside the 30-day erasure grace window. The body carries meta.deletedAt and meta.deletionScheduledAt. This is the signal to route the user to the reactivation screen — call POST /auth/reactivate. Only ever returned after the password is verified, so a wrong password still yields the generic 401 (no enumeration). |
| 403 | EMAIL_NOT_VERIFIED | Credentials are correct, but the email address was never confirmed. No session is issued; a fresh 6-digit code is emailed (unless one was sent in the last 60 seconds). Route the user to the verify-email screen and finish with POST /auth/verify-email. Only ever returned after the password is verified. |
| 429 | RATE_LIMITED | Too many login attempts from this IP. Respect Retry-After. |
Example error — 403 ACCOUNT_PENDING_DELETION
{
"type": "https://api.swappr.co.uk/errors/account-pending-deletion",
"title": "Account pending deletion",
"status": 403,
"code": "ACCOUNT_PENDING_DELETION",
"detail": "Account is scheduled for deletion",
"instance": "/api/v1/auth/login",
"requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2",
"meta": {
"deletedAt": "2026-06-14T02:45:54.729Z",
"deletionScheduledAt": "2026-07-14T02:45:54.729Z" // deletedAt + 30 days
}
}
Example error — 401
{
"type": "https://api.swappr.co.uk/errors/unauthenticated",
"title": "Authentication required",
"status": 401,
"code": "UNAUTHENTICATED",
"detail": "Invalid email or password",
"instance": "/api/v1/auth/login",
"requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2"
}
Side effects
- Records
lastSeenAton the user document. - Creates a
refresh_tokensrow keyed by the new session id (ULID).
See also
- Authentication — full token lifecycle, refresh, logout, socket tickets.
- Errors — the stable error code catalog.
curl
curl -X POST https://api.swappr.co.uk/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "alice@example.com",
"password": "correct horse battery staple"
}'