Authentication

The AutoPrintFarm API uses API keys for authentication. All requests must include a valid API key.

Getting Your API Key

1. Log in to your AutoPrintFarm dashboard
2. Navigate to Settings → API Keys
3. Click Create New API Key
4. Give it a descriptive name (e.g., “Production Server”)
5. Copy the key immediately (it won’t be shown again)

Using Your API Key

Include your API key in the Authorization header:

curl https://api.autoprintfarm.com/v1/printers \
  -H "Authorization: Bearer apf_live_abc123xyz789..."

Key Prefixes

API keys have different prefixes based on environment:

• apf_live_* - Production keys
• apf_test_* - Test mode keys
• apf_dev_* - Development keys

Authentication Methods

Bearer Token (Recommended)

Authorization: Bearer YOUR_API_KEY

fetch('https://api.autoprintfarm.com/v1/printers', {
  headers: {
    'Authorization': 'Bearer apf_live_abc123...'
  }
})

Basic Authentication (Legacy)

curl https://api.autoprintfarm.com/v1/printers \
  -u apf_live_abc123:

Note the colon (:) after the API key with no password.

API Key Scopes

Control what each API key can access:

Available Scopes

• printers:read - View printer information
• printers:write - Control printers
• jobs:read - View jobs
• jobs:write - Create and manage jobs
• analytics:read - Access analytics data
• webhooks:write - Manage webhooks
• admin:* - Full administrative access

Creating Scoped Keys

POST /v1/api-keys
{
  "name": "Job Manager",
  "scopes": ["jobs:read", "jobs:write", "printers:read"]
}

Checking Key Permissions

GET /v1/api-keys/current

Response:

{
  "id": "key_abc123",
  "name": "Production Server",
  "scopes": ["printers:*", "jobs:*"],
  "created_at": "2025-01-15T10:30:00Z",
  "last_used_at": "2025-10-06T14:25:00Z"
}

Security Best Practices

Keep Keys Secret

❌ Don’t commit keys to Git:

// Bad - hardcoded key
const API_KEY = 'apf_live_abc123...';

✅ Do use environment variables:

// Good - from environment
const API_KEY = process.env.AUTOPRINTFARM_API_KEY;

Use Environment Variables

.env file:

AUTOPRINTFARM_API_KEY=apf_live_abc123xyz789...

Code:

import os
api_key = os.environ.get('AUTOPRINTFARM_API_KEY')

Rotate Keys Regularly

Rotate API keys every 90 days:

1. Create new key
2. Update applications to use new key
3. Test thoroughly
4. Delete old key

Use Scoped Keys

Create keys with minimal required permissions:

// Good - limited scope for job submission service
{
  "name": "Job Submitter",
  "scopes": ["jobs:write", "printers:read"]
}

// Bad - unnecessary admin access
{
  "name": "Job Submitter",
  "scopes": ["admin:*"]
}

Monitor Key Usage

Review key usage regularly:

GET /v1/api-keys

Check for:

• Unused keys (delete them)
• Unexpected usage patterns
• Last used dates
• Request counts

Key Management

List All Keys

GET /v1/api-keys

{
  "keys": [
    {
      "id": "key_abc123",
      "name": "Production Server",
      "scopes": ["printers:*"],
      "created_at": "2025-01-15T10:30:00Z",
      "last_used_at": "2025-10-06T14:25:00Z"
    }
  ]
}

Revoke a Key

DELETE /v1/api-keys/key_abc123

Keys are immediately invalidated.

Roll Keys

Safely rotate without downtime:

POST /v1/api-keys/key_abc123/roll

Returns a new key while keeping the old one valid for 24 hours.

OAuth (Coming Soon)

OAuth 2.0 support for third-party integrations:

• Authorization code flow
• PKCE for mobile apps
• Refresh tokens
• Granular permissions

Join the beta →

Errors

Invalid Key

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid"
  }
}

Solutions:

• Verify key is correct
• Check for extra whitespace
• Ensure key hasn’t been revoked
• Confirm key prefix matches environment

Insufficient Permissions

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "insufficient_permissions",
    "message": "This API key lacks the required scope: printers:write"
  }
}

Solutions:

• Check key scopes
• Create new key with required permissions
• Contact admin to grant permissions

Rate Limited

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 3600 seconds"
  }
}

See Rate Limiting for details.

Testing Authentication

Test your API key:

curl https://api.autoprintfarm.com/v1/auth/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "authenticated": true,
  "key_id": "key_abc123",
  "organization": "Acme Manufacturing"
}

SDK Examples

JavaScript/Node.js

import { AutoPrintFarm } from '@autoprintfarm/sdk';

const client = new AutoPrintFarm({
  apiKey: process.env.AUTOPRINTFARM_API_KEY
});

const printers = await client.printers.list();

Python

from autoprintfarm import Client

client = Client(
    api_key=os.environ['AUTOPRINTFARM_API_KEY']
)

printers = client.printers.list()

Ruby

require 'autoprintfarm'

AutoPrintFarm.api_key = ENV['AUTOPRINTFARM_API_KEY']

printers = AutoPrintFarm::Printer.list

Next Steps

• Explore API endpoints
• Set up webhooks
• Try the API Explorer