Authentication API

User authentication endpoints.

Register

Create a new user account.

POST /api/v1/auth/register

Request

{
  "email": "user@example.com",
  "password": "SecureP@ss123",
  "first_name": "John",
  "last_name": "Doe",
  "organization_name": "Example Corp"
}

Response (201 Created)

{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 900
  }
}

Login

Authenticate and receive tokens.

POST /api/v1/auth/login

Request

{
  "email": "user@example.com",
  "password": "SecureP@ss123"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "role": "admin",
      "organization": {
        "id": "org-uuid",
        "name": "Example Corp"
      }
    },
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 900
  }
}

Error Response (401 Unauthorized)

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password"
  }
}

Refresh Token

Get a new access token using refresh token.

POST /api/v1/auth/refresh

Request

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response (200 OK)

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 900
  }
}

Logout

Invalidate current session.

POST /api/v1/auth/logout
Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "message": "Successfully logged out"
  }
}

Get Current User

Get authenticated user profile.

GET /api/v1/auth/me
Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "admin",
    "email_verified": true,
    "organization": {
      "id": "org-uuid",
      "name": "Example Corp",
      "plan": "pro"
    },
    "created_at": "2026-01-01T00:00:00Z"
  }
}

Password Reset Request

Request password reset email.

POST /api/v1/auth/password/forgot

Request

{
  "email": "user@example.com"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "message": "Password reset email sent"
  }
}

Password Reset

Reset password with token.

POST /api/v1/auth/password/reset

Request

{
  "token": "reset-token-from-email",
  "password": "NewSecureP@ss123",
  "password_confirmation": "NewSecureP@ss123"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "message": "Password successfully reset"
  }
}

Token Expiration

Token Type	Expiration
Access Token	15 minutes
Refresh Token	7 days
Reset Token	1 hour

Error Codes

Code	Description
INVALID_CREDENTIALS	Wrong email or password
EMAIL_NOT_VERIFIED	Email verification required
ACCOUNT_LOCKED	Too many failed attempts
TOKEN_EXPIRED	JWT token has expired
TOKEN_INVALID	JWT token is invalid