> For the complete documentation index, see [llms.txt](https://docs.ventrata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ventrata.com/capabilities/partners.md).

# Partner API Key

Optional. Get each Supplier's API key as soon as they set up your connection

{% hint style="info" %}
**This capability is optional.** You don't need it to integrate with Ventrata, and nothing else in these docs depends on it. It's an additional, quicker way to get API keys straight away when Suppliers set up your connection. If you're interested, get in touch with your Ventrata contact or email <connectivity@ventrata.com>.
{% endhint %}

To use this capability, add `ventrata/partners` to your `Octo-Capabilities` header and authenticate with the `Ventrata-Partner-Key` header.

By default, every Supplier ⇄ Partner connection on Ventrata has its own API key, and the Supplier sends that key to you when they connect. That stays the same. The Partner API Key only speeds up the hand-off. Ventrata issues your platform one partner-level key, and you use it to list every connection Suppliers have created for you, together with the connection's own API key. You then make normal OCTO calls (products, availability, bookings) with each returned `apiKey`, exactly as you would with a key the Supplier sent you.

It can help platforms that onboard many Suppliers and would rather not have Supplier credentials passing through email or local market teams. Account managers only need to share connection IDs, which are not secret.

{% hint style="warning" %}
The partner key returns live API keys for every Supplier connected to you. Store it like a root credential: keep it server-side, never expose it to local or market teams, and tell Ventrata straight away if it may have leaked.
{% endhint %}

## How it works

1. A Supplier enables your platform as a connection in their Ventrata account. They don't need to send you an API key. If they do, you can ignore it.
2. Your platform calls `GET /ventrata/partners/suppliers_connections` with your partner key.
3. The response lists every active connection for your platform, with the Supplier, the connection and the connection's `apiKey`.
4. For each connection, call the standard OCTO endpoints with `Authorization: Bearer {apiKey}`.
5. Poll the endpoint regularly, for example once an hour, to pick up new and removed connections.

## Endpoint summary

| Method | Path                                       | Description                                                                         |
| ------ | ------------------------------------------ | ----------------------------------------------------------------------------------- |
| `GET`  | `/ventrata/partners/suppliers_connections` | List your connections, each with its Supplier details and API key. **Recommended.** |
| `GET`  | `/ventrata/partner/connections`            | Older, lighter list of your connections: ID, names and API key only.                |

Base URL: `https://api.ventrata.com/octo`

### Request headers

| Header                 | Required | Description                                                                                                                               |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `Ventrata-Partner-Key` | Yes      | Your partner-level API key.                                                                                                               |
| `Octo-Capabilities`    | Yes      | Must include `ventrata/partners`. Add other capabilities (for example `octo/content`) to have them applied to the nested Supplier object. |
| `Octo-Fields`          | No       | Sparse fieldset, to return only the fields you need, for example `{connection{id},apiKey}`.                                               |

Don't send an `Authorization` header on these endpoints. They are authenticated by the partner key only.

## List suppliers' connections

`GET /ventrata/partners/suppliers_connections`

Returns an array with one entry per connection that Ventrata can authenticate. Connections that are disabled, discarded or linked to a discarded resource are left out of the list.

**Example request**

```http
GET /octo/ventrata/partners/suppliers_connections HTTP/1.1
Host: api.ventrata.com
Ventrata-Partner-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479
Octo-Capabilities: ventrata/partners
```

**Example response**

```json
[
  {
    "supplier": {
      "id": "84ea621d-b3c3-4cee-be5f-8cfdf00666cc",
      "name": "Example Tours",
      "endpoint": "https://api.ventrata.com/octo",
      "contact": {
        "website": "https://example-tours.com",
        "email": "hello@example-tours.com",
        "telephone": "+44 20 0000 0000",
        "address": "1 Example Street, London"
      }
    },
    "connection": {
      "id": "18bab50f-ac3b-4de5-9aee-18cbb4e62229",
      "name": "Example Tours / Your Platform"
    },
    "apiKey": "5d25b9be-9c1e-4a44-b6c6-117aa419cf6c"
  }
]
```

| Field        | Description                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `supplier`   | The Supplier that owns the connection. Uses the standard OCTO Supplier object, extended by any capabilities you request. |
| `connection` | The connection details: the same object returned by `GET /whoami` for that connection.                                   |
| `apiKey`     | The connection's API key. Use it as the Bearer token for all OCTO calls for this Supplier.                               |

## List partner connections (older endpoint)

`GET /ventrata/partner/connections`

Returns a flat list of your connections. Use `suppliers_connections` for new integrations.

```json
[
  {
    "id": "18bab50f-ac3b-4de5-9aee-18cbb4e62229",
    "name": "Example Tours / Your Platform",
    "supplier": "Example Tours",
    "reseller": null,
    "apiKey": "5d25b9be-9c1e-4a44-b6c6-117aa419cf6c"
  }
]
```

## Regions

Call either endpoint in any Ventrata region. The response combines connections from **all** regions. A connection hosted outside the default region returns an `apiKey` with a region prefix (for example `us1_…`). Use the key exactly as returned. The prefix routes your later calls to the right region.

If any region can't be reached, the whole request fails, so you never get a partial list. Retry later.

## Parent and child partners

If your organisation is set up in Ventrata as a parent partner with child partners (for example regional brands), the parent key returns the connections of the parent and all of its descendants. A child key returns only that child's connections (and those of its own children), never its parent's or siblings'.

## Errors

Authentication errors return HTTP `400` with `error: FORBIDDEN`.

| `errorCode`               | Meaning                                                                           |
| ------------------------- | --------------------------------------------------------------------------------- |
| `PARTNER_API_KEY_INVALID` | The `Ventrata-Partner-Key` header is missing, or doesn't match an active partner. |

Once a connection's `apiKey` is in use, an OCTO call can return `CONNECTION_DISABLED` or `CONNECTION_NOT_FOUND` if the Supplier has turned off or removed that connection. Drop it from your cache and refresh the list. See [Errors](https://docs.ventrata.com/getting-started/errors.md#authentication-errors).

## Best practices

* **Cache the list.** Refresh it on a schedule (hourly is enough) rather than before every booking call. The endpoint fans out across regions and loads every connection.
* **Don't loop it per Supplier.** One call returns all Suppliers. Calling it once for each Supplier multiplies the load and gets rate limited (`429`).
* **Use `Octo-Fields`** to request only the fields you need. The full Supplier object can be large.
* **Key products by connection.** Product IDs belong to a Supplier, and a Supplier can have more than one connection to you. Store the `connection.id` against each product you map.
