Skip to content

Auth

Authentication endpoints for registration, login, token refresh, and logout.

Base path: /api/v1/auth

Register

Creates a new user account and returns tokens. 

POST /api/v1/auth/register

Request body 

{
  "email": "user@example.com",
  "password": "Password123!",
  "first_name": "John",
  "last_name": "Doe"
}

Field Type Required Constraints
email string ✅ Valid email format
password string ✅ 8–72 characters
first_name string ❌ Max 100 characters
last_name string ❌ Max 100 characters

Response 201 Created 

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "is_active": true,
    "last_login": null,
    "roles": [],
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": null
  },
  "tokens": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "token_type": "bearer",
    "expires_in": 900
  }
}

Errors

Status Description
409 Email already registered
422 Validation error

Login

Authenticates a user and returns tokens. 

POST /api/v1/auth/login

Request body 

{
  "email": "user@example.com",
  "password": "Password123!"
}

Response 200 OK

Same structure as /register.

Errors

Status Description
401 Invalid email or password
401 Account is inactive
422 Validation error

Info

The same error message is returned for both invalid email and invalid password intentionally — an attacker should not be able to determine whether an email is registered.

Refresh Token

Issues a new access token and refresh token using a valid refresh token. 

POST /api/v1/auth/refresh

Request body 

{
  "refresh_token": "eyJ..."
}

Response 200 OK 

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 900
}

Token Rotation

Each refresh request invalidates the old refresh token and issues a new one. This limits the damage if a refresh token is stolen.

Errors

Status Description
401 Token is invalid or expired
401 Token has been revoked

Logout

Revokes the current refresh token. 

POST /api/v1/auth/logout

Request body 

{
  "refresh_token": "eyJ..."
}

Response 204 No Content

Info

Only the provided refresh token is revoked. Sessions on other devices remain active.

Logout All

Revokes all refresh tokens and increments token_version, immediately invalidating all active access tokens across all devices. 

POST /api/v1/auth/logout-all

Headers 

Authorization: Bearer <access_token>

Response 204 No Content

Warning

This action immediately invalidates all active sessions on all devices, including the current one. The user must log in again on every device.

Errors

Status Description
401 Not authenticated

Get Current User

Returns the authenticated user's profile. 

GET /api/v1/auth/me

Headers 

Authorization: Bearer <access_token>

Response 200 OK 

{
  "id": "uuid",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "is_active": true,
  "last_login": "2026-01-01T00:00:00Z",
  "roles": [
    {
      "id": "uuid",
      "name": "admin",
      "description": "Full access to everything"
    }
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": null
}

Errors

Status Description
401 Not authenticated
403 Account is inactive