Skip to main content

Authentication

Overview

This page covers authentication endpoints used to sign up, log in, refresh tokens and log out.

Endpoints

  • POST /api/v1/auth/signup — Create a new user (body: SignupRequest)
  • POST /api/v1/auth/login — Login and receive JWTs (body: LoginRequest)
  • POST /api/v1/auth/refresh — Refresh tokens
  • POST /api/v1/auth/logout — Revoke tokens (requires bearer auth)

Examples

Curl example: login

curl -X POST "{{baseUrl}}/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"secret"}'

Common Notes

  • All endpoints that require authentication return 401 when unauthorized.
  • Successful login returns a JSON object with access_token and refresh_token (see OpenAPI schema).

See also

POST /api/v1/auth/signup​

Summary: Create a new user account.

Request

  • Content-Type: application/json
  • Body schema: SignupRequest (see OpenAPI)

Responses

  • 200 — User created (returns SignupResponse)
  • 400 — Bad request (returns ErrorResponse)

Example

curl -X POST "{{baseUrl}}/api/v1/auth/signup" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"S3cureP@ss","name":"Jane Doe"}'

POST /api/v1/auth/login​

Summary: Authenticate and obtain JWT tokens.

Request

  • Content-Type: application/json
  • Body schema: LoginRequest

Responses

  • 200 — Returns JwtLoginResponse with access_token and refresh_token
  • 401 — Unauthorized (invalid credentials)

Example

curl -X POST "{{baseUrl}}/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"secret"}'

Notes

  • Store access_token securely and use it in Authorization: Bearer <token> headers.
  • Use refresh_token only to obtain new access tokens via /api/v1/auth/refresh.

POST /api/v1/auth/refresh​

Summary: Exchange a refresh token for new tokens.

Request

  • Content-Type: application/json
  • Body: { "refresh_token": "..." }

Responses

  • 200 — Returns JwtLoginResponse with new tokens

Example

curl -X POST "{{baseUrl}}/api/v1/auth/refresh" \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token":"<refresh-token>"}'

POST /api/v1/auth/logout​

Summary: Revoke tokens / logout the current user.

Security

  • Requires Authorization: Bearer <access_token> header.

Responses

  • 200 — Logged out (SuccessResponse)

Example

curl -X POST "{{baseUrl}}/api/v1/auth/logout" \
  -H 'Authorization: Bearer <access_token>'