Skip to main content

​
Authentication

The Voyager API uses token-based authentication. You authenticate with your username (email) and password to receive an access token, which you then use for all subsequent API requests.

​
Authentication Method

The Voyager API uses a simple token-based authentication flow:
  1. Login - Authenticate with your email and password
  2. Receive Token - Get an access token from the login response
  3. Use Token - Include the token in the Authorization header for all API requests

​
Token Authentication

Token authentication is the standard method for API access. It’s simple, secure, and works well for automated scripts and integrations.

​
Getting Your Token

Authenticate with your email and password to receive a token:
  • Python
  • curl
import requests

api_url = "https://voyager.lumafield.com"

response = requests.post(
    f"{api_url}/api/login",
    json={
        "email": "your-email@company.com",
        "password": "your-password"
    }
)
response.raise_for_status()

token = response.json()["token"]

​
Using Your Token

Include the token in the Authorization header:
  • Python
  • curl
headers = {
    "Authorization": f"Token {token}",
    "Content-Type": "application/json"
}

response = requests.get(
    f"{api_url}/api/v2/projects",
    headers=headers
)

​
Token Lifetime

Tokens expire after a period defined by TOKEN_LIFETIME_HOURS (typically 24 hours). When a token expires:
  1. You’ll receive a 401 Unauthorized response
  2. Re-authenticate to get a new token
  3. Update your requests with the new token

​
Logging Out

To invalidate a token before it expires:
  • Python
  • curl
response = requests.post(
    f"{api_url}/api/v2/logout",
    headers=headers
)
response.raise_for_status()

​
Security Best Practices

​
1. Never Commit Credentials

Never commit API credentials to version control: 
# ❌ Bad - hardcoded credentials
client = LumafieldAPIClient(
    api_url="https://voyager.lumafield.com",
    email="user@company.com",
    password="secret123"
)

# ✅ Good - use environment variables
import os
client = LumafieldAPIClient(
    api_url=os.getenv("VOYAGER_API_URL"),
    email=os.getenv("VOYAGER_EMAIL"),
    password=os.getenv("VOYAGER_PASSWORD")
)

​
2. Use Environment Variables

Set credentials as environment variables: Windows (PowerShell): 
$env:VOYAGER_API_URL="https://voyager.lumafield.com"
$env:VOYAGER_EMAIL="your-email@company.com"
$env:VOYAGER_PASSWORD="your-password"
Linux/macOS: 
export VOYAGER_API_URL="https://voyager.lumafield.com"
export VOYAGER_EMAIL="your-email@company.com"
export VOYAGER_PASSWORD="your-password"

​
3. Rotate Tokens Regularly

  • Log out when done with a session
  • Use new tokens for each session
  • Don’t reuse tokens across multiple applications

​
4. Handle Token Expiration

Implement token refresh logic: 
def make_authenticated_request(url, headers=None):
    """Make request with automatic token refresh"""
    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        return response
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            # Token expired, re-authenticate
            token = authenticate()
            headers["Authorization"] = f"Token {token}"
            return requests.get(url, headers=headers)
        raise

​
5. Use HTTPS Only

Always use HTTPS endpoints. Never send credentials over HTTP.

​
Error Responses

​
401 Unauthorized

Invalid or expired token: 
{
  "detail": "Invalid token."
}
Solution: Re-authenticate to get a new token.

​
403 Forbidden

Valid token but insufficient permissions: 
{
  "detail": "You do not have permission to perform this action."
}
Solution: Check that your account has the required capabilities.

​
API Access Requirements

To use the Voyager API, you need:
  1. A Lumafield account - Sign up at voyager.lumafield.com
  2. API access enabled - Contact support@lumafield.com to enable API access
  3. Required capabilities - Some endpoints require specific capabilities (e.g., PROJECT_DATA_EXPORT)

​
Next Steps