Partner API Key
Optional. Get each Supplier's API key as soon as they set up your connection
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.
How it works
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.
Your platform calls
GET /ventrata/partners/suppliers_connectionswith your partner key.The response lists every active connection for your platform, with the Supplier, the connection and the connection's
apiKey.For each connection, call the standard OCTO endpoints with
Authorization: Bearer {apiKey}.Poll the endpoint regularly, for example once an hour, to pick up new and removed connections.
Endpoint summary
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
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
Example response
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.
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.
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-Fieldsto 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.idagainst each product you map.