> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started for Agencies

> Mint a credential, exchange it for a token, and read your first agency data

This is the operational walkthrough for the agency surface: entitlement, credentials, the token exchange, and your first calls. If you arrived here first, read [The Agency API](/guides/agency-api) alongside it: that page covers what the surface answers, what it will not do, and how credential scope works.

If you are a carrier reading about the agencies you appoint, you want [Getting Started for Carriers & MGAs](/guides/getting-started) instead. The two surfaces are separate and a credential works on exactly one of them.

## 1. Check your organization is entitled

Agency API access is a product feature. If **Settings → API** is not in your Turris navigation, your organization does not have it yet; contact [support@turrisfi.com](mailto:support@turrisfi.com).

**Each area of the API needs the same product feature as the matching screen in the agency application.** If you can see a section in the app, its endpoints are available to your credential; if you cannot, they return **403** with an `errorType` of `product_feature_subscription_required` and a message naming the feature to ask for.

| Endpoints                                                                                                                                                                                                                       | Product feature         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `/actions-required`, `/entity-licenses`, `/producer-licenses`, `/entity-license-overview`, `/producer-license-overview`, `/entity-license-summary`, `/producer-license-summary`, `/license-requests`, `/license-request-groups` | License Management      |
| `/entity-appointments`, `/producer-appointments`                                                                                                                                                                                | Appointments            |
| `/markets` and its sub-resources                                                                                                                                                                                                | Markets                 |
| `/corporate-registration-filings`, `/corporate-registration-profiles`                                                                                                                                                           | Corporate Registrations |
| `/producers`                                                                                                                                                                                                                    | Distribution Management |
| `/entities`                                                                                                                                                                                                                     | Settings Org Structure  |
| `/contacts`                                                                                                                                                                                                                     | Settings Contacts       |
| `/documents`, `/document-compliance`                                                                                                                                                                                            | Settings Documents      |
| `/compliance-configs`                                                                                                                                                                                                           | License Compliance      |
| `/surplus-lines-filings`                                                                                                                                                                                                        | Surplus-Lines Filing    |

A 403 on one area never affects the others.

## 2. Mint a credential

<Steps>
  <Step title="Log into the Turris agency application">
    Use the environment you intend to integrate against. Sandbox first.
  </Step>

  <Step title="Go to Settings → API">
    Create an OAuth (machine-to-machine) client.
  </Step>

  <Step title="Store the client id and secret">
    The secret is stored hashed and cannot be retrieved again. If you lose it, delete the client and create another.
  </Step>
</Steps>

<Note>
  **An API Client is the recommended agency credential**, and this guide uses it. Agencies can also mint a [Restricted Access Token](/authentication#restricted-access-token) from the same settings page: a single long-lived secret, fenced by an exact-match IP allowlist, for callers that cannot perform the token exchange below. It reaches the same endpoints but never expires, so prefer the API Client wherever you have a backend.
</Note>

## 3. Exchange it for a token

```bash theme={null}
curl -X POST "https://public.api.sandbox.turrisfi.com/v2/auth/jwt" \
  -H "Content-Type: application/json" \
  -d '{ "clientId": "your-client-id", "clientSecret": "your-client-secret" }'
```

Tokens are valid for 60 minutes. **Cache them.** The token endpoint allows 4 requests per window (5 minutes in production, 60 seconds elsewhere), so a client that fetches a fresh token per API call will start failing almost immediately.

## 4. Read your entities first

```bash theme={null}
curl "https://public.api.sandbox.turrisfi.com/v2/downstream/entities" \
  -H "Authorization: Bearer <your-jwt-token>"
```

Start here rather than anywhere else: most other endpoints accept a `downstreamEntityId`, and this is where those ids come from.

## 5. Understand what your credential can see

**Your credential sees its own organization plus everything beneath it, and never anything above it.** Minted at your top company, it reaches the top company and every branch. Minted at a branch, it reaches that branch alone: not the parent, not sibling branches. [The Agency API](/guides/agency-api#the-one-thing-to-understand-before-you-build) explains why this is narrower than what the web application shows a branch user, and why you should mint at the top company if your integration covers the whole group.

### Narrowing to one entity

Every list accepts `downstreamEntityId` except three:

```bash theme={null}
curl "https://public.api.sandbox.turrisfi.com/v2/downstream/producers?downstreamEntityId=6610b3d2c2e0a51b8c0d1f02" \
  -H "Authorization: Bearer <your-jwt-token>"
```

The exceptions are the market sub-lists: `/v2/downstream/markets/{upstreamDownstreamAssociationId}/documents`, `/entity-contacts` and `/market-contacts` take only the association id plus `page` and `limit`.

An id outside your scope returns **404**, not 403. Treat a 404 on an id you believe is yours as a sign the credential was minted lower in the tree than you thought.

## Where to go next

[The Agency API](/guides/agency-api) maps what the surface answers, the limits worth knowing before you build (no webhooks, no download URL for a compliance document, no view into a carrier's own data), and the production checklist for [pagination](/guides/pagination), [idempotency](/guides/idempotency) and [rate limiting](/guides/rate-limiting).

Since there are no agency webhooks, the polling loop that replaces them starts at [Actions Required](/api-reference/v2/downstream/actions-required) and the [licensing summaries](/api-reference/v2/downstream/license-overview/entity-license-summary).


## Related topics

- [Introduction](/introduction.md)
- [The Agency API](/guides/agency-api.md)
- [Authentication](/authentication.md)