> ## Documentation Index
> Fetch the complete documentation index at: https://offergrid.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the Offergrid API

<Note>
  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](/docs/api-reference/authentication).
</Note>

## 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

### Step 1: Sign In to Offergrid

Visit [offergrid.io](https://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.

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

## Using Your API Key

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

```bash theme={null}
curl https://api.offergrid.io/provider/offers \
  -H "x-api-key: YOUR_TEAM_API_KEY"
```

### Example Requests

<CodeGroup>
  ```typescript TypeScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

## 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](/docs/api-reference/provider).

### Reseller Access

Every `/reseller/*` endpoint — catalog, address availability, orders, shareable
links, and customers. See the [Reseller API Reference](/docs/api-reference/reseller).

### Hybrid Access

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

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Generate new API keys periodically and revoke old ones to minimize security risks.
  </Accordion>

  <Accordion title="Use different keys for different environments">
    Use separate API keys for development, staging, and production environments.
  </Accordion>

  <Accordion title="Monitor key usage">
    Track API key usage in your Offergrid dashboard to detect any unusual activity.
  </Accordion>

  <Accordion title="Revoke compromised keys immediately">
    If you suspect an API key has been exposed, revoke it immediately and generate a new one.
  </Accordion>
</AccordionGroup>

## 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](/docs/api-reference/introduction#local-development) for how to
test safely.

## Error Responses

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

```json theme={null}
{
  "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](/docs/api-reference/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](mailto:support@offergrid.io)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.