Authentication

The GetPaidHQ API uses API key authentication to secure all requests. API keys are scoped to specific organizations and provide full access to all resources within that organization.

API keys

Obtaining API keys

API keys are generated from your organization settings in the GetPaidHQ dashboard:

1. Navigate to Settings → API Keys
2. Click Create API Key
3. Provide a descriptive name for the key
4. Copy the generated key immediately (it won't be shown again)

Key format

API keys follow this format:

pk_test_1234567890abcdef...  // Test environment
pk_live_1234567890abcdef...  // Production environment

Security considerations

• Never expose API keys in client-side code, repositories, or logs
• Use environment variables to store API keys in your applications
• Rotate keys regularly and immediately revoke compromised keys
• Use test keys for development and testing environments only

Making authenticated requests

Include your API key in the Authorization header using the Bearer scheme:

curl https://api.getpaidhq.com/api/customers \
  -H "Authorization: Bearer pk_live_1234567890abcdef..."

Alternative authentication methods

For backward compatibility, the API also accepts API keys in these formats:

Basic authentication:

curl https://api.getpaidhq.com/api/customers \
  -u "pk_live_1234567890abcdef:"

Query parameter (not recommended):

curl "https://api.getpaidhq.com/api/customers?api_key=pk_live_1234567890abcdef..."

Environment separation

Test environment

Use test API keys (pk_test_...) with the test base URL:

https://api.test.getpaidhq.com

Test environment features:

• Sandbox payments: No real money is processed
• Test webhooks: Events are sent to test endpoints
• Reset data: Test data can be cleared anytime
• Full functionality: All features available for testing

Production environment

Use live API keys (pk_live_...) with the production base URL:

https://api.getpaidhq.com

Production environment features:

• Real payments: Actual money processing
• Live webhooks: Events sent to production endpoints
• Data persistence: Permanent customer and billing data
• SLA guarantees: 99.9% uptime commitment

API key permissions

All API keys provide full access to your organization's resources. This includes:

• Read access: View all customers, subscriptions, payments, etc.
• Write access: Create, update, and delete resources
• Admin access: Manage settings, webhooks, and billing configuration

Best practices

• Environment separation: Use different keys for development, staging, and production
• Key rotation: Rotate API keys quarterly or after team member changes
• Monitoring: Monitor API key usage for unusual patterns
• Principle of least privilege: Consider using separate keys for different services

Error responses

Authentication errors return HTTP 401 status codes:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided"
  }
}

Common authentication errors:

Rate limiting by API key

Rate limits are applied per API key:

• Standard: 1,000 requests per minute
• Pro: 5,000 requests per minute
• Enterprise: Custom limits

Monitor your usage with rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642681200

SDK authentication

Official SDKs handle authentication automatically:

Node.js

import { GetPaidHQ } from '@getpaidhq/node';

const client = new GetPaidHQ({
  apiKey: process.env.GETPAIDHQ_API_KEY,
  environment: 'production' // or 'test'
});

Python

import getpaidhq

client = getpaidhq.Client(
    api_key=os.environ['GETPAIDHQ_API_KEY'],
    environment='production'  # or 'test'
)

Go

import "github.com/getpaidhq/go-sdk"

client := getpaidhq.NewClient(
    os.Getenv("GETPAIDHQ_API_KEY"),
    getpaidhq.Production, // or getpaidhq.Test
)

Webhook authentication

Webhooks use a different authentication mechanism. See the Webhooks documentation for details on verifying webhook signatures.

Support

If you're having authentication issues:

• Check your API key format and environment
• Verify your organization is active
• Review the error messages for specific guidance
• Contact support with your organization ID (never include your API key)