API Reference

Authentication API

Complete API reference for user authentication, registration, and session management.

Register User

Create a new user account with automatic tenant and welcome credits.

POST /api/v1/auth/register

# Request
curl -X POST https://www.vouchstone.ai/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123",
    "full_name": "John Doe",
    "company": "Acme Inc"
  }'

# Response
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "full_name": "John Doe",
  "tenant_id": "tenant_xyz789",
  "credits": 5000,
  "created_at": "2024-01-15T10:30:00Z"
}

Login

Authenticate a user and receive a JWT access token.

POST /api/v1/auth/login

# Request (form-urlencoded)
curl -X POST https://www.vouchstone.ai/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=securePassword123"

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Get Current User

Retrieve the authenticated user's profile and tenant information.

GET /api/v1/auth/me

# Request
curl https://www.vouchstone.ai/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "full_name": "John Doe",
  "is_active": true,
  "tenants": [
    {
      "id": "tenant_xyz789",
      "name": "Acme Inc",
      "role": "owner"
    }
  ]
}

Refresh Token

Get a new access token using a refresh token.

POST /api/v1/auth/refresh

# Request
curl -X POST https://www.vouchstone.ai/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Programmatic Access

There is currently no self-service API key issuance endpoint. Programmatic access uses the same JWT access token issued by POST /api/v1/auth/login above, sent as a Bearer token on every request — the same credential the dashboard itself uses. Use POST /api/v1/auth/refresh to obtain a new access token before the current one expires rather than re-authenticating with a password on every run.

Other Auth Endpoints

POST /api/v1/auth/forgot-password — request a password reset email
POST /api/v1/auth/reset-password — complete a password reset with the emailed token
POST /api/v1/auth/magic-link — request a passwordless magic-link sign-in email
GET /api/v1/auth/magic-link/{token} — exchange a magic-link token for an access token

Error Responses

# 401 Unauthorized
{
  "error": "unauthorized",
  "message": "Invalid or expired token"
}

# 403 Forbidden
{
  "error": "forbidden",
  "message": "Insufficient permissions for this action"
}

# 422 Validation Error
{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": [
    {"field": "email", "message": "Invalid email format"}
  ]
}

Continue to Agents API