Authentication

Learn how to securely authenticate with the PayArmorX API

API Keys

API keys provide secure access to your merchant account

API keys are long-lived credentials that allow you to authenticate API requests. Each key is tied to your merchant account and can be managed independently.

Security Warning

API keys are only shown once at generation. If you lose your key, you'll need to regenerate it. Never commit API keys to version control or share them publicly.

Generating API Keys

How to create and manage your API keys

Steps to Generate an API Key:

Log in to your merchant dashboard
Navigate to Settings → API Keys
Click "Generate Key"
Enter a descriptive name (e.g., "Production API", "Staging Environment")
Optionally set an expiration date
Copy and save your key immediately - you won't see it again!

Best Practice: Use different API keys for different environments (production, staging, development) and rotate them regularly.

Using API Keys in Requests

Include your API key in the Authorization header

Include your API key in the Authorization header of every authenticated request:

With Bearer prefix (recommended):

curl https://api.payarmorx.com/api/v1/whoami \
  -H "Authorization: Bearer pk_live_..."

Without Bearer prefix (also supported):

curl https://api.payarmorx.com/api/v1/whoami \
  -H "Authorization: pk_live_..."

Note: Some endpoints (like GET /inventory) are public and don't require authentication.

Key Management

Managing your API keys

Disable Keys

Temporarily disable a key without deleting it. The key will stop working immediately, but you can re-enable it later if needed.

Regenerate Keys

Create a new key and automatically disable the old one. Useful for key rotation or if you suspect a key has been compromised.

Expiration Dates

Set expiration dates on keys for additional security. Keys automatically stop working after expiration.

Multiple Keys

Create multiple keys for different purposes (production, staging, different applications, etc.). Each key can be managed independently.

Security Best Practices

Keep your API keys secure

Never commit API keys to version control - Use environment variables instead
Rotate keys regularly - Regenerate keys periodically for better security
Use different keys for different environments - Separate production and development keys
Set expiration dates - Automatically expire keys after a set time
Monitor key usage - Check the "Last Used" timestamp regularly
Disable unused keys - If a key is no longer needed, disable it
Use HTTPS only - Never send API keys over unencrypted connections
Store keys securely - Use secure storage solutions, never hardcode in client-side code

Authentication Error Responses

Common authentication errors and how to resolve them

401 Unauthorized - Missing API key

{
  "error": "Missing API key",
  "message": "Please provide an API key in the Authorization header"
}

Solution: Include your API key in the Authorization header

401 Unauthorized - Invalid API key

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

Solution: Verify your API key is correct and hasn't been regenerated

401 Unauthorized - API key disabled

{
  "error": "API key disabled",
  "message": "This API key has been disabled"
}

Solution: Re-enable the key in your dashboard or generate a new one

401 Unauthorized - API key expired

{
  "error": "API key expired",
  "message": "This API key has expired"
}

Solution: Generate a new API key or update the expiration date