Authentication

This is the overview — enough to get a key and make your first authenticated request. For role behaviour, exact error messages, key rotation, and troubleshooting, see the API authentication reference.

Overview

Offergrid uses Team API Keys for authentication. Your API key identifies your organization and determines whether you have provider, reseller, or hybrid access to the platform.

Getting Your API Key

Visit offergrid.io and sign in to your account.

Step 2: Navigate to Settings

Go to your team settings or API settings page in the dashboard.

Step 3: Generate an API Key

Click Generate New API Key and securely save the key. You won’t be able to see it again after leaving the page.

Keep your API key secure and never expose it in client-side code, public repositories, or version control systems. Treat it like a password.

Using Your API Key

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

curl https://api.offergrid.io/provider/offers \
  -H "x-api-key: YOUR_TEAM_API_KEY"

Example Requests

const response = await fetch('https://api.offergrid.io/provider/offers', {
  method: 'GET',
  headers: {
    'x-api-key': process.env.OFFERGRID_API_KEY,
  },
});

const offers = await response.json();

import requests
import os

response = requests.get(
  'https://api.offergrid.io/provider/offers',
  headers={
    'x-api-key': os.environ['OFFERGRID_API_KEY']
  }
)

offers = response.json()

const apiKey = process.env.OFFERGRID_API_KEY;

fetch('https://api.offergrid.io/provider/offers', {
  headers: {
    'x-api-key': apiKey,
  },
})
  .then((res) => res.json())
  .then((offers) => console.log(offers));

API Key Permissions

Your API key’s permissions are based on your team’s role:

Provider Access

Every /provider/* endpoint — offers, orders, markets, webhooks, brands, and customers. See the Provider API Reference.

Reseller Access

Every /reseller/* endpoint — catalog, address availability, orders, shareable links, and customers. See the Reseller API Reference.

Hybrid Access

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

Best Practices

Store keys securely

Use environment variables or secure key management systems (like AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault) to store API keys. Never hardcode keys in your application code.

Rotate keys regularly

Generate new API keys periodically and revoke old ones to minimize security risks.

Use different keys for different environments

Use separate API keys for development, staging, and production environments.

Monitor key usage

Track API key usage in your Offergrid dashboard to detect any unusual activity.

Revoke compromised keys immediately

If you suspect an API key has been exposed, revoke it immediately and generate a new one.

API Base URLs

https://api.offergrid.io

This is the only Offergrid-hosted environment. There is no separate sandbox host and no test-mode key, so requests you make are real — see Local development for how to test safely.

Error Responses

If authentication fails, you’ll receive a 401 Unauthorized response:

{
  "statusCode": 401,
  "message": "Invalid team API key",
  "error": "Unauthorized"
}

Common authentication errors:

Missing API key: The x-api-key header was not provided
Invalid API key: The provided key doesn’t exist or has been revoked
Wrong value sent: The header name was sent as the value instead of the key

A 403 is different — the key is valid, but your team’s role does not cover that endpoint family. Every status code and its exact message is listed in Errors.

Need Help?

If you’re having trouble with authentication:

Check that you’re using the correct header name (x-api-key)
Verify that your API key hasn’t been revoked
Ensure your team has the appropriate provider or reseller role
Contact support at support@offergrid.io

Getting Started

Documentation

Overview

Getting Your API Key

Step 2: Navigate to Settings

Step 3: Generate an API Key

Using Your API Key

Example Requests

API Key Permissions

Provider Access

Reseller Access

Hybrid Access

Best Practices

API Base URLs

Error Responses

Need Help?

​Overview

​Getting Your API Key

​Step 1: Sign In to Offergrid

​Step 2: Navigate to Settings

​Step 3: Generate an API Key

​Using Your API Key

​Example Requests

​API Key Permissions

​Provider Access

​Reseller Access

​Hybrid Access

​Best Practices

​API Base URLs

​Error Responses

​Need Help?

Overview

Getting Your API Key

Step 1: Sign In to Offergrid

Step 2: Navigate to Settings

Step 3: Generate an API Key

Using Your API Key

Example Requests

API Key Permissions

Provider Access

Reseller Access

Hybrid Access

Best Practices

API Base URLs

Error Responses

Need Help?