Getting Started

Authentication

Copy page

All Verso API requests require authentication using a Bearer token. This guide explains how to obtain and use your API credentials.

API Key Authentication

Verso uses API key-based authentication. Your API key acts as a Bearer token that must be included in every request.

Header Format

Include your API key in the Authorization header:

Authorization Header
 
Authorization: Bearer YOUR_API_KEY

Example Request

Authenticated Request
 
curl -X GET "https://api.sandbox.verso.io/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Obtaining API Keys

Sandbox Environment

To access the sandbox environment:

1. Contact your account manager at Verso
2. Receive your sandbox credentials including:
   • API Key
   • Division ID
   • Payroll ID
3. Use the sandbox base URL: https://api.sandbox.verso.io

Production Environment

For production access:

1. Complete your integration testing in sandbox
2. Request production credentials from your account manager
3. Use the production base URL: https://api.verso.io

Security Best Practices

Store Keys Securely

Environment Variable
 
export VERSO_API_KEY="your-api-key-here"

Using Environment Variable
 
curl -X GET "https://api.sandbox.verso.io/users" \
  -H "Authorization: Bearer $VERSO_API_KEY"

Key Rotation

• Rotate API keys periodically
• Immediately revoke compromised keys by contacting support
• Use separate keys for development and production

Network Security

• Always use HTTPS (TLS 1.2+)
• Implement IP allowlisting when possible
• Monitor API usage for anomalies

Tenant Isolation

Verso operates in a multi-tenant architecture. Your API key is bound to a specific tenant, ensuring:

• Data Isolation: You can only access your organization's data
• Division Scoping: Operations are scoped to your assigned divisions
• Automatic Injection: Tenant context is automatically applied to all requests

Error Responses

401 Unauthorized

Code
 
{
  "type": "https://httpstatuses.com/401",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

Causes:

• Missing Authorization header
• Invalid API key
• Expired API key

403 Forbidden

Code
 
{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access denied to requested resource"
}

Causes:

• Attempting to access another tenant's data
• Insufficient permissions for the operation
• Resource not within your division scope

Next Steps

• Quickstart - Run your first payroll
• Error Handling - Understanding API errors
• API Reference - Explore all endpoints