Authentication

Overview

The Empfio API uses JWT Bearer tokens. Include your token in the Authorization header of every request.

Authorization: Bearer <your_token>

All endpoints (except registration, login, and public webhook endpoints) require authentication.

Base URL

Environment	Base URL
Self-hosted (dev)	`http://localhost:8001`
Production	Your configured domain (e.g. `https://api.your-domain.com`)

Getting a token

Register a new account

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your_password",
  "full_name": "Your Name",
  "organization_name": "Your Business"
}

Response (201 Created):

{
  "user_id": "550e8400-...",
  "email": "you@example.com",
  "organization_id": "660f9500-...",
  "organization_name": "Your Business",
  "access_token": "eyJ...",
  "token_type": "bearer"
}

Log in

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your_password"
}

Response (200 OK):

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "user_id": "550e8400-...",
  "email": "you@example.com",
  "full_name": "Your Name",
  "organization_id": "660f9500-...",
  "organization_name": "Your Business"
}

Empfio supports OAuth login via Google, Facebook, and Outlook. The frontend handles the OAuth redirect flow and exchanges the authorization code:

POST /api/v1/auth/oauth/callback
Content-Type: application/json

{
  "provider": "google",
  "code": "authorization_code_from_oauth",
  "redirect_uri": "https://your-app.com/auth/callback"
}

Response:

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "user_id": "550e8400-...",
  "email": "you@example.com",
  "full_name": "Your Name",
  "organization_id": "660f9500-...",
  "is_new_user": false
}

Supported providers: google, facebook, outlook.

User profile

Get current user

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

Response:

{
  "id": "550e8400-...",
  "email": "you@example.com",
  "full_name": "Your Name",
  "is_active": true,
  "is_verified": true,
  "oauth_provider": "local",
  "organization_id": "660f9500-...",
  "organization_name": "Your Business",
  "created_at": "2026-01-15T10:00:00Z"
}

Update profile

PATCH /api/v1/auth/me
Authorization: Bearer <token>
Content-Type: application/json

{
  "full_name": "Updated Name"
}

Token details

Tokens are signed with HS256 (HMAC-SHA256)
The token payload contains sub (user ID), org (organization ID), and exp (expiration timestamp)
All data returned is scoped to the user's organization — you can only access leads, bookings, and conversations belonging to your organization

Error responses

Status	Meaning
`401 Unauthorized`	Missing or invalid token
`403 Forbidden`	Valid token but the user's account is inactive
`409 Conflict`	Email already registered (registration only)

Authentication

On this page