Authentication

API Token Authentication

All API requests must include a valid Bearer token in the Authorization header:

Authorization: Bearer {your-80-character-api-token}

Token Management

• Obtain Token: API tokens are generated when creating API Users
• Token Security: Treat tokens like passwords - store securely
• Token Rotation: Tokens can be regenerated from the admin interface
• Token Validation: Tokens are validated on every request

Authentication Process

Token Verification

When you make an API request, the system:

1. Extracts the Bearer token from the Authorization header
2. Searches for a user with matching api_token
3. Verifies the user has guard_name = 'api'
4. Confirms the user status is active
5. Proceeds with the request if all checks pass

Authentication Headers

Required Headers

Content-Type: application/json
Authorization: Bearer your-api-token-here
Accept: application/json

Example Request

curl -X POST "https://your-domain.com/api/submissions/workflow/123" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abc123def456ghi789jkl012mno345pqr678stu901vwx234yzA567BCD890EFG123HIJ456" \
  -H "Accept: application/json" \
  -d '{"name": "John Doe"}'

Authentication Errors

Common Error Codes

Error Code	HTTP Status	Description	Solution
TOKEN_MISSING	401	No Authorization header provided	Add Bearer token to request
TOKEN_INVALID	401	Invalid or expired token	Verify token is correct and user is active
USER_INACTIVE	401	API user account is disabled	Contact admin to activate account
GUARD_MISMATCH	401	Token belongs to web user, not API user	Use proper API user account

Error Response Examples

Missing Token

{
  "error": "Authentication token is required",
  "code": "TOKEN_MISSING"
}

Invalid Token

{
  "error": "Invalid or expired authentication token",
  "code": "TOKEN_INVALID"
}

Inactive User

{
  "error": "API user account is inactive",
  "code": "USER_INACTIVE"
}

Token Security Best Practices

Storage

• Environment Variables: Store tokens in secure environment variables
• Configuration Management: Use secure configuration management systems
• Never Hardcode: Don't embed tokens directly in source code
• Version Control: Never commit tokens to version control systems

Rotation

• Regular Rotation: Rotate tokens periodically (quarterly/annually)
• Immediate Rotation: Rotate immediately if compromise suspected
• Graceful Transition: Plan for token updates in production systems
• Multiple Environments: Use different tokens for dev/staging/production

Monitoring

• Usage Tracking: Monitor token usage patterns
• Failed Attempts: Alert on repeated authentication failures
• Unusual Activity: Watch for requests from unexpected locations
• Audit Logs: Maintain comprehensive authentication logs

Implementation Examples

JavaScript/Node.js

const axios = require('axios');

const apiToken = process.env.OSPROV_API_TOKEN;
const workflowId = 123;

const submitData = async (data) => {
  try {
    const response = await axios.post(
      `https://your-domain.com/api/submissions/workflow/${workflowId}`,
      data,
      {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${apiToken}`,
          'Accept': 'application/json'
        }
      }
    );
    return response.data;
  } catch (error) {
    if (error.response?.status === 401) {
      throw new Error('Authentication failed - check API token');
    }
    throw error;
  }
};

Python

import requests
import os

api_token = os.getenv('OSPROV_API_TOKEN')
workflow_id = 123

def submit_data(data):
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {api_token}',
        'Accept': 'application/json'
    }
    
    response = requests.post(
        f'https://your-domain.com/api/submissions/workflow/{workflow_id}',
        json=data,
        headers=headers
    )
    
    if response.status_code == 401:
        raise Exception('Authentication failed - check API token')
    
    response.raise_for_status()
    return response.json()

PHP

<?php
$apiToken = getenv('OSPROV_API_TOKEN');
$workflowId = 123;

function submitData($data) {
    global $apiToken, $workflowId;
    
    $headers = [
        'Content-Type: application/json',
        'Authorization: Bearer ' . $apiToken,
        'Accept: application/json'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "https://your-domain.com/api/submissions/workflow/{$workflowId}");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 401) {
        throw new Exception('Authentication failed - check API token');
    }
    
    return json_decode($response, true);
}
?>

Troubleshooting Authentication

Checklist

1. ✅ Token Format: Ensure token is exactly 80 characters
2. ✅ Header Format: Use Bearer prefix (note the space)
3. ✅ User Type: Confirm using API User, not normal account
4. ✅ User Status: Verify API User is active
5. ✅ Token Validity: Check if token was recently regenerated
6. ✅ Environment: Ensure using correct token for environment

Debug Steps

1. Test Token: Use a simple curl request to verify authentication
2. Check Logs: Review server logs for authentication errors
3. Verify User: Confirm API User exists and is active in admin panel
4. Token Regeneration: Try regenerating the API token
5. Contact Admin: Work with system administrator if issues persist