Skip to main content
Turris exposes two APIs over one platform. They share a host, an OAuth flow and an error envelope. They answer different questions, and your credential works on exactly one of them.

​
The one question

I appoint agencies

You are an MGA, carrier or wholesaler. You want to read the agencies and producers you appoint: their licenses, appointments, documents and compliance standing.Carrier & MGA API at /v2/upstream/*

I am the agency

You are an agency or brokerage. You want to read your own record: your entities and branches, your producers, your licenses and appointments, and the markets you place business with.Agency API at /v2/downstream/*
If both descriptions sound partly true, you are an MGA that also holds retail business. You still get one credential per Turris organization, so the question is which organization you are calling as, not which you are.

​
Why the path names you

From v2 onward the segment after the version says which kind of organization the caller is:
The segment exists because an agency asking for “its licenses” means something different from a carrier asking for “its licenses”. Without a word naming the caller, the two questions cannot share a path. There is nothing to configure. You write the same literal word into your base URL every time, and it is the word for the organization your credential belongs to.

​
What happens if you pick wrong

A wrong-surface call returns 403 with errorType set to invalid_organization_category.
That is a different 403 from the two others you may hit. Branch on errorType, never on the message text.

​
How to tell which credential you hold

Call the shared token test. It reports the surface your credential is for, so you never have to guess:
The response carries orgCategory. Anything else in your integration follows from that one value.
orgCategory is a four-value enum, so do not branch with an if/else that treats “not upstreamEntity” as an agency. The two enterprise values exist today and a credential carrying one would be misclassified by that shape. Match the value you expect and treat anything else as neither surface.
Four paths carry no persona segment, because the token itself identifies the organization: auth/jwt, auth/test-oauth, auth/test-restricted-access-token and heartbeat. Both surfaces call them the same way, and this holds on v1 as well as v2. So an agency credential is served on POST /v1/auth/jwt and GET /v1/heartbeat even though every persona-scoped v1 route refuses it. Prefer the v2 paths anyway: only GET /v2/auth/test-oauth reports orgCategory.

​
Versions differ by surface

v1 predates the persona model and serves carriers only. That is the reason v2 exists: without a persona in the path there was nowhere to put an agency-facing API. Both v1 and v2 are stable and supported. /v2/upstream carries every v1 operation except seven: the four auth and heartbeat paths, which moved to the unsegmented /v2/auth/* and /v2/heartbeat, and three deprecated dangerously- endpoints, which have documented successors. See versioning.

​
The same records, two vocabularies

The two surfaces name the same rows differently, and each side’s word is correct on its own side. This table is the only place both columns appear together, so it is worth reading once.
The relationship record has two id field names for one value. The carrier surface and every webhook payload call it downstreamEntityAssociationId. The agency surface calls it upstreamDownstreamAssociationId. They are the same identifier viewed from opposite ends, and neither is being renamed.

​
What is shared, and where it lives

Everything on this tab applies to both surfaces: authentication, environments, pagination, rate limiting, request and response shape, error handling, idempotency, versioning and security. Everything specific to one surface lives on that surface’s own tab, including its getting-started guide and its complete endpoint reference.

Carrier & MGA API

What it covers, what it cannot do, and how to make your first call.

Agency API

What it covers, how credential scope works, and how to make your first call.

Related topics

Support and Contact InformationIntroductionAuthentication