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

# Introduction

> Base URL, authentication, roles, and where to go next in the Offergrid API

The Offergrid API is a B2B marketplace API connecting service providers with
reseller partners, streamlining the distribution and sale of essential services
like internet and electricity.

## Quick facts

| | |
| - | - |
| **Base URL** | `https://api.offergrid.io` |
| **Protocol** | HTTPS only |
| **Auth** | `x-api-key: YOUR_TEAM_API_KEY` header on every authenticated request |
| **Format** | JSON request and response bodies |
| **Version** | 1 — no version segment in the URL, no version header |
| **Specs** | [Provider](/docs/openapi/openapi-provider.json) · [Reseller](/docs/openapi/openapi-reseller.json) · [Public](/docs/openapi/openapi-public.json) · [Full](/docs/openapi/openapi.json) |

## Your first request

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

A `200` with a JSON array means you are connected and authenticated. A `401`
means the key or header is wrong; a `403` means the key is fine but your team's
role does not cover that endpoint. See [Errors](/docs/api-reference/errors).

## What you can do

Which half of the API you use depends on your team's role. The role is carried
by the API key — there is nothing else to configure.

<CardGroup cols={2}>
  <Card title="Provider API" icon="building" href="/docs/api-reference/provider">
    Publish and manage service offers, define market coverage, receive and
    fulfill orders, and register webhooks.
  </Card>

  <Card title="Reseller API" icon="handshake" href="/docs/api-reference/reseller">
    Browse the catalog, check what is available at a service address, place
    orders for customers, and track fulfillment.
  </Card>

  <Card title="Public API" icon="globe" href="/docs/api-reference/public">
    Unauthenticated endpoints powering shareable reseller links and the
    consumer storefront. No API key.
  </Card>

  <Card title="Agent briefing" icon="robot" href="/docs/agents">
    A single page with everything needed to generate a correct integration.
  </Card>
</CardGroup>

**Hybrid teams** hold both roles and reach every endpoint with the same key.

## Before you build

Four pages that will save you a debugging session each:

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/api-reference/authentication">
    Issuing, rotating, and revoking keys; role behaviour; auth errors
  </Card>

  <Card title="API conventions" icon="list-check" href="/docs/api-reference/conventions">
    List responses, identifiers, timestamps, money, and idempotency
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/docs/api-reference/errors">
    Every status code, what causes it, and a retry-safe client
  </Card>

  <Card title="Versioning" icon="code-branch" href="/docs/api-reference/versioning">
    What we promise not to break, and how deprecations work
  </Card>
</CardGroup>

## Local development

`https://api.offergrid.io` is the only Offergrid-hosted environment — there is
no separate sandbox host, and no test-mode key. If you want an environment to
experiment against, run the API locally from the monorepo; it listens on
`http://localhost:3000` by default and speaks the same contract as production.

<Warning>
  Because there is no sandbox, requests against `api.offergrid.io` are real:
  orders you create are real orders, and they notify real providers. Use a
  dedicated team for integration testing, and delete test data when you are
  done.
</Warning>

## Getting an API key

Sign in at [offergrid.io](https://offergrid.io), then **Settings → API Keys →
Generate New Key**. The key is shown once — store it in a secrets manager or
environment variable immediately.

<Warning>
  Keep your API key server-side. Never put it in client-side code, a mobile
  binary, or a repository. Treat it like a password.
</Warning>


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