Skip to main content
This is the detailed reference. For a first key and a first request, start with the Authentication overview.

Authentication Method

All Offergrid API endpoints require authentication using a Team API Key passed in the request headers.

API Key Header

Include your API key in the x-api-key header with every request:

Example Requests

Team Roles and Permissions

Your API key’s permissions depend on your team’s role:

Provider Teams

Access to every /provider/* endpoint: offers, orders, markets, webhooks, brands, and customers. See the Provider API Reference for the full list.

Reseller Teams

Access to every /reseller/* endpoint: catalog, address availability, orders, shareable links, and customers. See the Reseller API Reference for the full list.

Hybrid Teams

Some teams have both provider AND reseller roles. Hybrid teams can access all endpoints with the same API key.

Authentication Errors

401 Unauthorized

The key is missing, malformed, or not recognized. The message tells you which:
Solution: check the header name is exactly x-api-key, that the value is the key itself, and that the key has not been revoked.

403 Forbidden

The key is valid, but your team’s role does not cover this endpoint family.
The reseller equivalent reads Reseller access required. Your team does not have reseller privileges. Solution: call the endpoints your role allows, or contact support@offergrid.io to have your team set up as hybrid.
A 403 is about the endpoint family, not a specific record. Requesting another team’s offer or order returns 404, not 403 — see Errors.

Security Best Practices

Store Keys Securely

✅ Good:
❌ Bad:
For production, use:
  • AWS: AWS Secrets Manager
  • Azure: Azure Key Vault
  • GCP: Secret Manager
  • HashiCorp: Vault
  • 1Password: 1Password CLI
Generate new API keys periodically and revoke old ones:
  • Every 90 days for active keys
  • Immediately if compromised
  • When team members leave

Use HTTPS Only

https://api.offergrid.io is the only base URL. Plain HTTP is not served, and there is no alternate hostname — anything else is not Offergrid.

Don’t Expose Keys Client-Side

Never include API keys in:
  • Frontend JavaScript code
  • Mobile app binaries
  • Public repositories
  • Client-side API calls
Make API calls from your backend server only.

Separate Keys by Environment

Use different API keys for:
  • Development: Testing and development work
  • Staging: Pre-production testing
  • Production: Live customer transactions
This limits the impact of compromised keys.

Rate Limiting

The authenticated Provider and Reseller APIs are not rate limited today — there is no quota, no X-RateLimit-* header, and no 429 on any /provider/* or /reseller/* endpoint. The unauthenticated /public/shop/* write endpoints are limited per IP. That is a property of the current stage, not a guarantee. Handle 429 in your client anyway, and do not build a tight polling loop. See Rate limits for exactly what is enforced and what we will do before introducing limits here.

Managing API Keys

Generating Keys

  1. Sign in to offergrid.io
  2. Navigate to SettingsAPI Keys
  3. Click Generate New Key
  4. Copy immediately - you won’t see it again!
  5. Store securely in environment variables or secrets manager

Revoking Keys

If a key is compromised:
  1. Go to SettingsAPI Keys
  2. Find the compromised key
  3. Click Revoke
  4. Generate a new key
  5. Update your applications
Revoked keys return 401 Unauthorized immediately.

Key Naming

Give keys descriptive names:
  • Production API Key
  • Staging Environment
  • Development - John's Laptop
  • CI/CD Pipeline
This helps identify which key to revoke if needed.

Troubleshooting

”Invalid API key” error

Check:
  1. Header name is exactly x-api-key (lowercase, with hyphen)
  2. API key was copied correctly (no extra spaces)
  3. API key hasn’t been revoked
  4. Request is going to correct base URL

”Forbidden” error

Check:
  1. Team has the correct role (provider or reseller)
  2. Endpoint matches team role
  3. Account is active and verified

Keys not working in production

Check:
  1. Using production API key (not development key)
  2. Environment variables set correctly
  3. Key has proper permissions
  4. Not hitting rate limits

Next Steps

Provider API Reference

Every provider endpoint

Reseller API Reference

Every reseller endpoint

Errors

Every status code and a retry-safe client

Rate limits

What is limited, and what is not