Authentication

The Centro Access API uses API Key authentication to secure access to work order data. Each API key is associated with an organization and has specific permissions that control what operations it can perform.

How API Keys Work

API keys in Centro Access are:

• Organization-specific - Each key belongs to one organization and can only access that organization's data
• Permission-based - Keys have specific permissions (view, add, change, delete) for work orders
• Trackable - All API requests are logged with the API key used
• Revocable - Keys can be deactivated without affecting other keys

Getting an API Key

Step 1: Access the API Keys Section

1. Log into the Centro Access web application
2. Navigate to Settings → API Keys
3. Click "Create New API Key"

Step 2: Configure the API Key

1. Name: Give your API key a descriptive name (e.g., "Integration System", "Mobile App")
2. Description: Add details about what this key will be used for
3. Permissions: Select the required permissions:
   • view_workorder - List and retrieve work orders
   • add_workorder - Create new work orders
   • change_workorder - Update existing work orders (future functionality)
   • delete_workorder - Delete work orders (future functionality)

Step 3: Save and Copy

1. Click "Create API Key"
2. Important: Copy the API key immediately - it's only shown once!
3. Store the key securely in your application's configuration

Using API Keys

Authorization Header

Include your API key in the Authorization header of every request:

Authorization: Api-Key your-api-key-here

Complete Example Request

curl -X GET "https://app.centroaccess.com/api/v1/external/workorders/" \
  -H "Authorization: Api-Key abc123def456ghi789" \
  -H "Content-Type: application/json"

Required Permissions

Different API endpoints require specific permissions:

Endpoint	HTTP Method	Required Permission
List Work Orders	GET /workorders/	view_workorder
Create Work Order	POST /workorders/	add_workorder
Get Work Order Details	GET /workorders/{id}/	view_workorder

Best Practice

Create separate API keys for different purposes. For example:

• Read-only key with only view_workorder for reporting systems
• Full access key with view_workorder and add_workorder for integration systems

Security Best Practices

1. Store Keys Securely

• Never commit API keys to version control
• Use environment variables or secure configuration management
• Rotate keys regularly (every 90 days recommended)

# Good: Use environment variables
export CENTRO_ACCESS_API_KEY="your-api-key-here"

# Bad: Hardcode in source code
api_key = "abc123def456ghi789"  # DON'T DO THIS

2. Limit Permissions

Only grant the minimum permissions required:

# If you only need to read data, don't request write permissions
Required permissions: view_workorder only

# If you need to create work orders, include both:
Required permissions: view_workorder, add_workorder

3. Monitor Usage

• Regularly review API key usage in the Centro Access dashboard
• Set up alerts for unusual activity patterns
• Deactivate unused keys immediately

4. Use HTTPS

Always use HTTPS for API requests to protect your API key in transit:

# Good: HTTPS
curl -X GET "https://app.centroaccess.com/api/v1/external/workorders/"

# Bad: HTTP (API key transmitted in plain text)
curl -X GET "http://app.centroaccess.com/api/v1/external/workorders/"

Error Responses

Invalid API Key

Status Code: 401 Unauthorized

{
  "detail": "Invalid API key"
}

Common causes:

• API key is incorrect or mistyped
• API key has been revoked or deactivated
• Missing Api-Key prefix in Authorization header

Insufficient Permissions

Status Code: 403 Forbidden

{
  "error": "Insufficient permissions",
  "required_permission": "workorder.add_workorder"
}

Common causes:

• API key doesn't have the required permission for this endpoint
• Organization is inactive or suspended

Malformed Authorization Header

Status Code: 401 Unauthorized

{
  "detail": "Invalid authorization header format"
}

Common causes:

• Missing Api-Key prefix: Use Api-Key your-key not just your-key
• Using wrong format like Bearer your-key

Rate Limiting

API keys are subject to rate limiting to ensure fair usage:

• 1,000 requests per hour per API key
• 100 requests per minute (burst limit)

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1635000000

When you exceed rate limits, you'll receive:

Status Code: 429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Code Examples

Python

import os
import requests

# Get API key from environment variable
API_KEY = os.getenv('CENTRO_ACCESS_API_KEY')
BASE_URL = "https://app.centroaccess.com/api/v1/external"

headers = {
    "Authorization": f"Api-Key {API_KEY}",
    "Content-Type": "application/json"
}

# Make authenticated request
response = requests.get(f"{BASE_URL}/workorders/", headers=headers)

if response.status_code == 200:
    work_orders = response.json()
    print(f"Retrieved {work_orders['count']} work orders")
else:
    print(f"Error: {response.status_code} - {response.text}")

JavaScript/Node.js

const axios = require('axios');

// Get API key from environment variable
const API_KEY = process.env.CENTRO_ACCESS_API_KEY;
const BASE_URL = 'https://app.centroaccess.com/api/v1/external';

const headers = {
  'Authorization': `Api-Key ${API_KEY}`,
  'Content-Type': 'application/json'
};

// Make authenticated request
async function getWorkOrders() {
  try {
    const response = await axios.get(`${BASE_URL}/workorders/`, { headers });
    console.log(`Retrieved ${response.data.count} work orders`);
    return response.data;
  } catch (error) {
    if (error.response) {
      console.error(`Error: ${error.response.status} - ${error.response.data}`);
    } else {
      console.error(`Network error: ${error.message}`);
    }
  }
}

getWorkOrders();

cURL

# Set your API key as an environment variable
export API_KEY="your-api-key-here"

# Make authenticated request
curl -X GET "https://app.centroaccess.com/api/v1/external/workorders/" \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json"

Managing API Keys

Rotating Keys

It's good security practice to rotate API keys regularly:

1. Create a new API key with the same permissions
2. Update your applications to use the new key
3. Test that everything works with the new key
4. Deactivate the old key

Monitoring Usage

Monitor your API key usage through the Centro Access dashboard:

• View request counts and patterns
• Monitor for unusual activity
• Track which endpoints are being used most
• Identify potential security issues

Deactivating Keys

If an API key is compromised or no longer needed:

1. Go to Settings → API Keys
2. Find the key in question
3. Click "Deactivate"
4. The key will immediately stop working

Next Steps

Now that you understand authentication, you're ready to start using the API:

• List Work Orders → Query and filter work orders
• Create Work Order → Programmatically create work orders
• Get Work Order Details → Retrieve detailed work order information