Authentication

Bizon Platform supports multiple authentication methods: JWT tokens, Google OAuth, and API keys.

JWT Authentication

The primary authentication method uses JSON Web Tokens (JWT).

Registration

Create a new user and organization:

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!",
    "name": "John Doe",
    "organization_name": "My Company"
  }'

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "owner"
  },
  "organization": {
    "id": "uuid",
    "name": "My Company",
    "slug": "my-company-abc123"
  }
}

Login

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!"
  }'

Using Tokens

Include the access token in the Authorization header:

curl http://localhost:8000/api/pipelines \
  -H "Authorization: Bearer eyJ..."

Token Refresh

Access tokens expire after 24 hours. Use the refresh token to get new tokens:

curl -X POST http://localhost:8000/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJ..."}'

Google OAuth

Users can sign in with Google for a passwordless experience.

Configuration

Set the following environment variables:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:8000/api/auth/google/callback
FRONTEND_URL=http://localhost:5173

OAuth Flow

1. User clicks “Sign in with Google” in the UI
2. Redirect to GET /api/auth/google
3. Google authenticates user
4. Callback to GET /api/auth/google/callback
5. Platform creates/updates user and redirects to frontend with tokens

Account Linking

Existing users can link their Google account:

# Get redirect URL (authenticated)
curl http://localhost:8000/api/auth/link/google \
  -H "Authorization: Bearer eyJ..."

# Returns: {"redirect_url": "https://accounts.google.com/..."}

Unlinking OAuth

curl -X DELETE http://localhost:8000/api/auth/unlink/google \
  -H "Authorization: Bearer eyJ..."

API Keys

API keys provide programmatic access without user interaction.

Creating an API Key

cURL

curl -X POST http://localhost:8000/api/api-keys \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "expires_in_days": 90
  }'

Response

{
  "id": "uuid",
  "name": "CI/CD Pipeline",
  "key": "biz_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "key_prefix": "biz_live_XXX",
  "expires_at": "2024-06-01T00:00:00Z",
  "created_at": "2024-03-01T00:00:00Z"
}

Important: The full key is returned only once. Store it securely.

Using API Keys

Include the API key in the X-API-Key header:

curl http://localhost:8000/api/pipelines \
  -H "X-API-Key: biz_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Key Format

• Prefix: biz_live_ (9 characters)
• Random: 32 characters from secrets.token_urlsafe(24)
• Total: 44 characters

Listing Keys

curl http://localhost:8000/api/api-keys \
  -H "Authorization: Bearer eyJ..."

Revoking Keys

curl -X DELETE http://localhost:8000/api/api-keys/{key_id} \
  -H "Authorization: Bearer eyJ..."

Role-Based Access Control

Roles

Role	Permissions
owner	Full access, can transfer ownership
admin	Full access except ownership transfer
member	Create/edit pipelines and connectors
viewer	Read-only access

Domain Role Overrides

Grant elevated permissions within specific domains:

# Add domain role override
curl -X POST http://localhost:8000/api/users/{user_id}/domain-roles \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "uuid",
    "role": "admin"
  }'

Rules:

• Only admin or member roles can be assigned as overrides
• Overrides can only elevate, not demote
• owner and admin org roles are not affected by overrides

Password Management

Changing Password

curl -X PUT http://localhost:8000/api/auth/password \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "OldPassword123!",
    "new_password": "NewPassword456!"
  }'

Password Requirements

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one number
• At least one special character

Security Configuration

Setting	Default	Description
JWT_SECRET_KEY	Required	Secret for JWT signing
JWT_ALGORITHM	HS256	JWT algorithm
JWT_ACCESS_TOKEN_EXPIRE_MINUTES	1440	Access token lifetime (24h)
JWT_REFRESH_TOKEN_EXPIRE_DAYS	7	Refresh token lifetime

Generate a secure JWT secret:

openssl rand -hex 32