API Keys

API keys provide a way to authenticate server-to-server requests or grant third-party access to your APSO API.

Overview

APSO supports two types of API keys:

Creating API Keys

From Dashboard

1. Navigate to your service (or organization settings)
2. Go to Settings > API Keys
3. Click Create API Key
4. Configure the key:
   • Name — Descriptive name
   • Permissions — Read, Write, or Full Access
   • Expiration — Optional expiry date
5. Click Create
6. Copy the key immediately — it won’t be shown again

From CLI

# Create a service API key
apso api-key create --name "Integration Key" --permissions read
 
# Create with expiration
apso api-key create --name "Temp Key" --expires 30d
 
# List all keys
apso api-key list

Using API Keys

Request Header

Include the API key in the X-API-Key header:

curl -X GET https://api.example.com/api/v1/projects \
  -H "X-API-Key: apso_sk_live_xxxxxxxxxxxxx"

SDK Configuration

import { ApsoClient } from '@apso/sdk';
 
const client = new ApsoClient({
  baseUrl: 'https://api.example.com',
  apiKey: process.env.APSO_API_KEY,
});

Key Permissions

Read Only

• GET requests only
• Cannot create, update, or delete
• Best for: Analytics, reporting, dashboards

Write Only

• POST, PATCH, DELETE requests
• Cannot read data
• Best for: Webhook receivers, import tools

Full Access

• All HTTP methods
• Complete API access
• Best for: Full integrations, admin tools

Custom Permissions

For granular control:

{
  "permissions": {
    "projects": ["read", "write"],
    "users": ["read"],
    "tasks": ["read", "write", "delete"]
  }
}

Key Scopes

Service Scope

Access limited to a single service:

apso_sk_svc_xxxxxxxxxx

• Tied to one service
• Permissions apply to that service only
• Deleted when service is deleted

Organization Scope

Access to all services in the organization:

apso_sk_org_xxxxxxxxxx

• Access all organization services
• Must be used carefully
• Best for: Organization-wide tools

Key Security

Best Practices

1. Never expose in client code

   // WRONG - exposed to users
   const client = new ApsoClient({
     apiKey: 'apso_sk_live_xxxxx', // Never do this!
   });
    
   // RIGHT - server-side only
   const client = new ApsoClient({
     apiKey: process.env.APSO_API_KEY,
   });

2. Use minimal permissions

   • Grant only the permissions needed
   • Prefer read-only when possible

3. Set expiration dates

   • Temporary integrations should expire
   • Review and rotate regularly

4. Use environment variables

   APSO_API_KEY=apso_sk_live_xxxxx

5. Monitor usage

   • Check API logs regularly
   • Set up alerts for unusual activity

Key Rotation

To rotate a key:

1. Create a new key with the same permissions
2. Update your integration to use the new key
3. Verify the integration works
4. Revoke the old key

# Create new key
apso api-key create --name "Integration Key v2"
 
# After updating integration, revoke old key
apso api-key revoke apso_sk_live_oldkey

Managing Keys

View Keys

From dashboard:

1. Go to Settings > API Keys
2. See all active keys with:
   • Name
   • Created date
   • Last used
   • Permissions

Edit Key

Keys cannot be edited after creation. To change permissions:

1. Create a new key with desired permissions
2. Update your integration
3. Revoke the old key

Revoke Key

From dashboard:

1. Go to Settings > API Keys
2. Find the key to revoke
3. Click Revoke
4. Confirm revocation

From CLI:

apso api-key revoke apso_sk_live_xxxxx

Warning: Revoked keys stop working immediately.

Rate Limits

API keys have rate limits based on your plan:

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

Monitoring

API Key Logs

View usage in the dashboard:

1. Go to Settings > API Keys
2. Click on a key
3. View Usage tab

Logs show:

• Request count
• Endpoints accessed
• Error rates
• Geographic distribution

Alerts

Set up alerts for:

• High error rates
• Unusual request patterns
• Near rate limit
• Key approaching expiration

Troubleshooting

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid API key"
}

Solutions:

1. Check key is not revoked
2. Verify key hasn’t expired
3. Ensure correct header name (X-API-Key)
4. Check for extra whitespace

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions"
}

Solutions:

1. Check key permissions match the request
2. Verify key scope covers the service
3. Create a new key with correct permissions

429 Too Many Requests

{
  "statusCode": 429,
  "message": "Rate limit exceeded"
}

Solutions:

1. Implement request throttling
2. Cache responses when possible
3. Upgrade plan for higher limits
4. Contact support for temporary increases

Related

• Authentication →
• Testing Your API →
• Monitoring →