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 thex-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. Themessage tells you which:
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.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
Use environment variables
Use environment variables
✅ Good:❌ Bad:
Use secrets management
Use secrets management
For production, use:
- AWS: AWS Secrets Manager
- Azure: Azure Key Vault
- GCP: Secret Manager
- HashiCorp: Vault
- 1Password: 1Password CLI
Rotate keys regularly
Rotate keys regularly
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
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
Rate Limiting
The authenticated Provider and Reseller APIs are not rate limited today — there is no quota, noX-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
- Sign in to offergrid.io
- Navigate to Settings → API Keys
- Click Generate New Key
- Copy immediately - you won’t see it again!
- Store securely in environment variables or secrets manager
Revoking Keys
If a key is compromised:- Go to Settings → API Keys
- Find the compromised key
- Click Revoke
- Generate a new key
- Update your applications
401 Unauthorized immediately.
Key Naming
Give keys descriptive names:Production API KeyStaging EnvironmentDevelopment - John's LaptopCI/CD Pipeline
Troubleshooting
”Invalid API key” error
Check:- Header name is exactly
x-api-key(lowercase, with hyphen) - API key was copied correctly (no extra spaces)
- API key hasn’t been revoked
- Request is going to correct base URL
”Forbidden” error
Check:- Team has the correct role (provider or reseller)
- Endpoint matches team role
- Account is active and verified
Keys not working in production
Check:- Using production API key (not development key)
- Environment variables set correctly
- Key has proper permissions
- 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