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

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

If your team is registered as a provider, you can access:

* `/provider/offers` - Create and manage service offerings
* `/provider/orders` - View and fulfill orders from resellers

### Reseller Access

If your team is registered as a reseller, you can access:

* `/reseller/catalog` - Browse available service offers
* `/reseller/orders` - Place and track orders

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

<Tabs>
  <Tab title="Production">
    ```
    https://api.offergrid.io
    ```

    Use this URL for production workloads and live customer transactions.
  </Tab>

  <Tab title="Local Development">
    ```
    http://localhost:3000
    ```

    If you're running the Offergrid API locally for development or testing.
  </Tab>
</Tabs>

## Error Responses

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

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized - invalid 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
* **Insufficient permissions**: Your team role doesn't have access to the requested endpoint

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