API Authentication

Overview

The deployERP API uses Bearer token authentication. All API requests must include a valid API key in the Authorization header. This guide covers authentication setup, best practices, and troubleshooting.

Authentication Methods

API Keys

Long-lived tokens for programmatic access

OAuth 2.0

Coming soon: OAuth flow for third-party apps

API Key Management

Creating API Keys

Generate API keys from your dashboard:

Navigate to API Settings

Go to Settings → API Keys in your dashboard

Create New Key

Click Generate New API Key

Configure Permissions

Select required permissions for the key

Set Expiration

Choose expiration date (optional)

Save Key

Copy and securely store the generated key

API keys are shown only once. Store them securely in a password manager or secrets management system.

API Key Format

Bearer dep_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Key components:

dep_ - Prefix identifying deployERP keys
live - Environment (live/test)
a1b2c3... - Unique key identifier

Using API Keys

Request Headers

Include your API key in the Authorization header:

curl -X GET https://api.deployerp.com/v1/servers \
  -H "Authorization: Bearer dep_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json"

import requests

headers = {
    'Authorization': 'Bearer dep_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.deployerp.com/v1/servers',
    headers=headers
)

const axios = require('axios');

const config = {
  headers: {
    'Authorization': 'Bearer dep_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
    'Content-Type': 'application/json'
  }
};

const response = await axios.get(
  'https://api.deployerp.com/v1/servers',
  config
);

client := &http.Client{}
req, _ := http.NewRequest("GET", "https://api.deployerp.com/v1/servers", nil)
req.Header.Add("Authorization", "Bearer dep_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6")
req.Header.Add("Content-Type", "application/json")

resp, err := client.Do(req)

Environment Variables

Best practice: Store API keys in environment variables:

# .env file
DEPLOYERP_API_KEY=dep_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# Usage in code
import os
api_key = os.getenv('DEPLOYERP_API_KEY')

API Key Permissions

Permission Scopes

Configure granular permissions for API keys:

Scope	Description	Operations
`servers:read`	View server information	GET /servers
`servers:write`	Create/update servers	POST, PATCH /servers
`servers:delete`	Delete servers	DELETE /servers
`instances:read`	View instances	GET /instances
`instances:write`	Create/update instances	POST, PATCH /instances
`instances:delete`	Delete instances	DELETE /instances
`backups:read`	View backups	GET /backups
`backups:write`	Create backups	POST /backups
`teams:read`	View team info	GET /teams
`teams:write`	Manage teams	POST, PATCH /teams
`billing:read`	View billing info	GET /invoices

Permission Examples

Read-Only Key
Deployment Key
Admin Key

{
  "name": "monitoring-key",
  "permissions": [
    "servers:read",
    "instances:read",
    "backups:read"
  ]
}

{
  "name": "ci-deployment",
  "permissions": [
    "servers:read",
    "instances:read",
    "instances:write",
    "backups:write"
  ]
}

{
  "name": "admin-key",
  "permissions": [
    "servers:*",
    "instances:*",
    "backups:*",
    "teams:*"
  ]
}

Security Features

IP Whitelisting

Restrict API key usage by IP address:

{
  "name": "production-key",
  "permissions": ["instances:*"],
  "ip_whitelist": [
    "203.0.113.0/24",    // Office network
    "198.51.100.45",     // CI/CD server
    "2001:db8::/32"      // IPv6 range
  ]
}

Key Expiration

Set expiration dates for enhanced security:

{
  "name": "temporary-key",
  "permissions": ["servers:read"],
  "expires_at": "2024-12-31T23:59:59Z",
  "auto_rotate": true,
  "rotation_period": "90d"
}

Rate Limiting per Key

Different rate limits based on key type:

Key Type	Requests/Hour	Burst Limit	Use Case
Standard	1,000	100/min	Normal usage
High Volume	10,000	1,000/min	Automation
Limited	100	10/min	Testing
Unlimited	No limit	No limit	Enterprise

Authentication Errors

Common Error Responses

Missing Authentication
Invalid Token
Expired Token
Insufficient Permissions
IP Restricted

{
  "error": {
    "code": "authentication_required",
    "message": "No authentication token provided",
    "status": 401
  }
}

{
  "error": {
    "code": "invalid_token",
    "message": "The provided API key is invalid",
    "status": 401
  }
}

{
  "error": {
    "code": "token_expired",
    "message": "The API key has expired",
    "status": 401,
    "expired_at": "2024-01-01T00:00:00Z"
  }
}

{
  "error": {
    "code": "insufficient_permissions",
    "message": "This API key lacks required permissions",
    "status": 403,
    "required": ["instances:write"],
    "provided": ["instances:read"]
  }
}

{
  "error": {
    "code": "ip_not_allowed",
    "message": "Request from this IP is not allowed",
    "status": 403,
    "your_ip": "192.0.2.1",
    "allowed_ips": ["203.0.113.0/24"]
  }
}

Error Handling

Implement proper error handling:

import requests
from requests.exceptions import RequestException

def make_api_request(endpoint, api_key):
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    try:
        response = requests.get(
            f'https://api.deployerp.com/v1/{endpoint}',
            headers=headers
        )
        response.raise_for_status()
        return response.json()
    
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            print("Authentication failed. Check your API key.")
        elif e.response.status_code == 403:
            print("Permission denied. Check key permissions.")
        else:
            print(f"HTTP error: {e}")
        return None
    
    except RequestException as e:
        print(f"Request failed: {e}")
        return None

async function makeApiRequest(endpoint, apiKey) {
  try {
    const response = await fetch(
      `https://api.deployerp.com/v1/${endpoint}`,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 401:
          throw new Error('Authentication failed');
        case 403:
          throw new Error('Permission denied');
        default:
          throw new Error(error.message);
      }
    }
    
    return await response.json();
    
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

Key Rotation

Automatic Rotation

Enable automatic key rotation:

{
  "rotation_enabled": true,
  "rotation_period": "90d",
  "notification_email": "[email protected]",
  "grace_period": "7d"
}

Manual Rotation

Rotate keys programmatically:

# Rotate API key
curl -X POST https://api.deployerp.com/v1/api-keys/{key_id}/rotate \
  -H "Authorization: Bearer CURRENT_API_KEY" \
  -H "Content-Type: application/json"

# Response
{
  "old_key": {
    "id": "key_abc123",
    "expires_at": "2024-02-07T00:00:00Z"
  },
  "new_key": {
    "id": "key_xyz789",
    "value": "dep_live_new_key_value",
    "created_at": "2024-01-31T00:00:00Z"
  }
}

Best Practices

Secure Storage

Never commit API keys to version control
Use environment variables or secret managers
Encrypt keys at rest
Rotate keys regularly

Least Privilege

Grant minimum required permissions
Create separate keys for different purposes
Review permissions regularly
Remove unused keys

Monitoring

Track API key usage
Set up alerts for unusual activity
Review access logs
Monitor failed authentication attempts

Key Hygiene

Name keys descriptively
Document key purposes
Set expiration dates
Use IP whitelisting when possible

Testing Authentication

Test Endpoint

Verify your authentication setup:

# Test authentication
curl -X GET https://api.deployerp.com/v1/auth/test \
  -H "Authorization: Bearer YOUR_API_KEY"

# Success response
{
  "authenticated": true,
  "key_id": "key_abc123",
  "permissions": ["servers:read", "instances:*"],
  "rate_limit": {
    "limit": 1000,
    "remaining": 999,
    "reset": "2024-01-31T15:00:00Z"
  }
}

Debug Headers

Enable debug headers for troubleshooting:

curl -X GET https://api.deployerp.com/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Debug-Auth: true"

# Response headers
X-Auth-Key-ID: key_abc123
X-Auth-Permissions: servers:read,instances:*
X-Auth-IP-Check: passed
X-Auth-Rate-Limit: 999/1000

SDK Authentication

Python SDK

from deployerp import Client

# Initialize client with API key
client = Client(api_key="dep_live_your_api_key")

# Or use environment variable
client = Client()  # Reads from DEPLOYERP_API_KEY env var

# Test authentication
try:
    client.auth.test()
    print("Authentication successful")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")

Node.js SDK

const { DeployERPClient } = require('@deployerp/sdk');

// Initialize with API key
const client = new DeployERPClient({
  apiKey: 'dep_live_your_api_key'
});

// Or use environment variable
const client = new DeployERPClient();
// Reads from process.env.DEPLOYERP_API_KEY

// Test authentication
try {
  await client.auth.test();
  console.log('Authentication successful');
} catch (error) {
  console.error('Authentication failed:', error);
}

Introduction

Servers

Instances

Backups

Teams

Webhooks

Overview

Authentication Methods

API Keys

OAuth 2.0

API Key Management

Creating API Keys

API Key Format

Using API Keys

Request Headers

Environment Variables

API Key Permissions

Permission Scopes

Permission Examples

Security Features

IP Whitelisting

Key Expiration

Rate Limiting per Key

Authentication Errors

Common Error Responses

Error Handling

Key Rotation

Automatic Rotation

Manual Rotation

Best Practices

Testing Authentication

Test Endpoint

Debug Headers

SDK Authentication

Python SDK

Node.js SDK

​Overview

​Authentication Methods

API Keys

OAuth 2.0

​API Key Management

​Creating API Keys

​API Key Format

​Using API Keys

​Request Headers

​Environment Variables

​API Key Permissions

​Permission Scopes

​Permission Examples

​Security Features

​IP Whitelisting

​Key Expiration

​Rate Limiting per Key

​Authentication Errors

​Common Error Responses

​Error Handling

​Key Rotation

​Automatic Rotation

​Manual Rotation

​Best Practices

​Testing Authentication

​Test Endpoint

​Debug Headers

​SDK Authentication

​Python SDK

​Node.js SDK

​Related Documentation

Overview

Authentication Methods

API Key Management

Creating API Keys

API Key Format

Using API Keys

Request Headers

Environment Variables

API Key Permissions

Permission Scopes

Permission Examples

Security Features

IP Whitelisting

Key Expiration

Rate Limiting per Key

Authentication Errors

Common Error Responses

Error Handling

Key Rotation

Automatic Rotation

Manual Rotation

Best Practices

Testing Authentication

Test Endpoint

Debug Headers

SDK Authentication

Python SDK

Node.js SDK

Related Documentation