Authentication

All API requests require authentication. Goblins supports two authentication methods:

• API Keys: For scripts, CI/CD pipelines, and programmatic access
• Web Session: Automatic when using the web interface

API Keys

API keys are the recommended way to authenticate with the Goblins API for automation and integrations.

Creating an API Key

1. Log in to the Goblins web interface
2. Navigate to API Keys in your account settings
3. Click Create API Key
4. Enter a descriptive name (e.g., GitHub Actions, Local Development)
5. Click Create
6. Copy the key immediately - it won't be shown again

Save Your Key

API keys are only displayed once when created. Store your key securely - you cannot retrieve it later.

API Key Format

API keys follow this format:

gob_abc123def456...

All keys start with gob_ followed by a random string.

Using API Keys

Include your API key in the Authorization header:

curl -H "Authorization: Bearer gob_your_api_key_here" \
  https://your-goblins-instance.com/api/services/

Alternatively, use the X-API-Key header:

curl -H "X-API-Key: gob_your_api_key_here" \
  https://your-goblins-instance.com/api/services/

API Key Limits

• Maximum of 10 active API keys per account
• Keys can be revoked at any time
• Optional expiration dates can be set when creating keys

Managing API Keys

In the API Keys section, you can:

• View all keys: See names, creation dates, and last used timestamps
• Revoke keys: Immediately disable a key
• Track usage: See when each key was last used

Best Practices

1. Use descriptive names: Name keys by their purpose (e.g., CI/CD Pipeline, Monitoring Script)
2. Rotate regularly: Create new keys periodically and revoke old ones
3. Limit scope: Create separate keys for different systems
4. Never commit keys: Don't include API keys in source code
5. Use environment variables: Store keys in environment variables or secret managers

Making Authenticated Requests

Using cURL

# List all services
curl -H "Authorization: Bearer gob_your_key" \
  https://your-goblins-instance.com/api/services/

# Create a service
curl -X POST https://your-goblins-instance.com/api/services/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-service", "image": "nginx:1.25", "port": 80}'

Using Python

import requests

API_KEY = "gob_your_api_key_here"
BASE_URL = "https://your-goblins-instance.com/api"

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

# List services
response = requests.get(f"{BASE_URL}/services/", headers=headers)
services = response.json()

# Create a service
new_service = {
    "name": "my-service",
    "image": "nginx:1.25",
    "port": 80
}
response = requests.post(f"{BASE_URL}/services/", json=new_service, headers=headers)

Using JavaScript/Node.js

const API_KEY = 'gob_your_api_key_here';
const BASE_URL = 'https://your-goblins-instance.com/api';

// List services
const response = await fetch(`${BASE_URL}/services/`, {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});
const services = await response.json();

// Create a service
const newService = await fetch(`${BASE_URL}/services/`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'my-service',
    image: 'nginx:1.25',
    port: 80
  })
});

Error Responses

401 Unauthorized

You'll receive this error if:

• No authentication is provided
• The API key is invalid or revoked
• The API key has expired

{
  "detail": "Authentication credentials were not provided."
}

Solution: Check that your API key is correct and active.

403 Forbidden

You'll receive this error if:

• You're trying to access another user's resources
• The API key doesn't have access to the requested resource

{
  "detail": "You do not have permission to perform this action."
}

Solution: Ensure you're accessing resources owned by your account.

Rate Limiting

Authenticated requests are subject to rate limits:

Operation	Limit
Resource operations	100/hour
Secret access	100/hour

When rate limited:

{
  "detail": "Request was throttled. Expected available in 3600 seconds."
}

Solution: Wait for the specified time or optimize your request patterns.

Security Recommendations

Storing API Keys

Do:

• Use environment variables
• Use secret management tools (AWS Secrets Manager, HashiCorp Vault, etc.)
• Use CI/CD secret storage (GitHub Secrets, GitLab CI Variables, etc.)

Don't:

• Commit keys to version control
• Share keys via email or chat
• Store keys in plain text files
• Include keys in client-side code

Example: Using Environment Variables

# Set the environment variable
export GOBLINS_API_KEY="gob_your_api_key_here"

# Use in scripts
curl -H "Authorization: Bearer $GOBLINS_API_KEY" \
  https://your-goblins-instance.com/api/services/

Example: GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Goblins
        env:
          GOBLINS_API_KEY: ${{ secrets.GOBLINS_API_KEY }}
        run: |
          curl -X PATCH https://goblins.example.com/api/services/$SERVICE_ID/ \
            -H "Authorization: Bearer $GOBLINS_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"image": "myapp:${{ github.sha }}"}'

Next Steps

• API Reference - Full API documentation
• Services - Deploy and manage services