Authentication

The Turris Public API supports two authentication methods. Which are available to you depends on what kind of organization you are.

Authentication Methods

Method	Available to	Best For	Security Level
OAuth (M2M)	Carriers and agencies	Server-to-server integrations	High - JWT with expiration
Restricted Access Token	Carriers and agencies	Callers that cannot perform a token exchange	Token + IP allowlist, no expiry

Both methods reach the same endpoints. OAuth is recommended wherever the calling system has a backend: its tokens expire after 60 minutes and rotate, whereas a Restricted Access Token never expires and stays valid until you delete it.

Carrier and agency credentials

A credential belongs to one organization, and that organization’s kind decides which endpoints it can reach. There is no credential that reaches both.

Carrier (upstream entity)

Reaches /v1/* and /v2/upstream/*. Both authentication methods are available.Mint from Settings → API in the carrier application. Requires the Public API product feature, and each area needs the feature of its matching screen; see Getting Started.

Agency (downstream entity)

Reaches /v2/downstream/*. Both authentication methods are available.Mint from Settings → API in the agency application. Requires the Public API product feature, and each area needs the feature of its matching screen; see Getting Started for Agencies.

Using a credential on the other surface returns 403 with errorType invalid_organization_category. That is the intended answer rather than a configuration problem: the two surfaces answer different questions, and an agency reading carrier endpoints would be reading other organizations’ data. Entitlement is verified on every request, on both versions. A credential does not expire, so an organization that stops being a Turris customer, or has a product feature switched off, receives 403 with product_feature_subscription_required rather than continuing to work. See Error Handling.

The agency surface is v2 only. There is no v1 agency surface and there will not be one — v1 predates the persona split and is upstream-only by construction.

OAuth Authentication (Recommended)

OAuth uses Machine-to-Machine (M2M) JWT tokens for authentication. This is the preferred method for production integrations.

Step 1: Create API Client

Open Settings → API in your own Turris application. Carriers use the carrier app; agencies use the agency app. The application you mint from decides which surface the credential reaches.
Click Create API Client
Store your client_id and client_secret securely

Never expose your client secret in frontend code. Store credentials securely in environment variables or a secrets manager.

Step 2: Get Access Token

Exchange your credentials for a JWT. The token endpoint carries no persona segment, so the same call issues a carrier token or an agency token depending on the credential you send:

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

Response:

{
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  },
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-01-30T12:34:56.789Z"
}

On v1 the same call is POST /v1/auth/jwt. It stays available for carriers already on v1; there is no v1 agency equivalent, so an agency credential only has the v2 path.

Step 3: Use the Token

Include the token in the Authorization header. GET /v2/heartbeat is one of the four paths with no persona segment, so it answers for a carrier credential and an agency credential alike:

curl -X GET "https://public.api.live.turrisfi.com/v2/heartbeat" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

After that the paths diverge: a carrier calls /v1/* or /v2/upstream/*, an agency calls /v2/downstream/*. See Which API is mine?.

Token Lifecycle

Property	Value
Time-to-Live (TTL)	60 minutes
Refresh	Request new token before expiry

Implement token caching in your application. Request a new token only when the current one is about to expire (e.g., 5 minutes before expiry).

Test Your Token

GET /v2/auth/test-oauth confirms the token is valid and reports which surface it is for:

curl -X GET "https://public.api.live.turrisfi.com/v2/auth/test-oauth" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success Response:

{
  "data": {
    "message": "If you see this message, your OAuth token is valid!",
    "orgCategory": "downstreamEntity"
  },
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-01-30T12:34:56.789Z"
}

orgCategory is upstreamEntity (carrier, MGA or wholesaler) or downstreamEntity (agency, brokerage or branch). It is a four-value enum: enterpriseUpstreamEntity and enterpriseDownstreamEntity also exist, for surfaces that are not routable yet, so match the value you expect rather than treating “not upstreamEntity” as an agency. Run this call first whenever a request comes back 403: it is the one request that tells you, without guessing, which paths the credential you just sent can reach. Full walkthrough in Which API is mine?. The v1 equivalent, GET /v1/auth/test-oauth, returns the message only and no orgCategory. Use the v2 path for this check even when the rest of your integration is on v1.

Restricted Access Token

Restricted Access Tokens provide a simpler authentication method with IP-based security.

Step 1: Create Token

Open Settings → API in your own Turris application (carrier, agency)
Choose Add New → Restricted Access Token
Add the exact IP addresses your requests will originate from
Store your token securely — it is shown once and only its hash is kept

Step 2: Use the Token

Include the token in the x-restricted-access-token header. The surface rule is the same as for OAuth. A carrier token reaches /v1/* and /v2/upstream/*; an agency token reaches /v2/downstream/*. Presenting one on the other surface returns 403, and there is no v1 agency surface. Carrier:

curl -X GET "https://public.api.live.turrisfi.com/v1/downstream-entity-associations" \
  -H "x-restricted-access-token: your-restricted-access-token"

Agency:

curl -X GET "https://public.api.live.turrisfi.com/v2/downstream/producers" \
  -H "x-restricted-access-token: your-restricted-access-token"

Security Model

The Restricted Access Token guard performs three validations:

Token Presence - Checks for the x-restricted-access-token header
Token Validity - Validates the token against stored hashes
IP Allowlist - Verifies the request originates from an allowed IP address

Requests from IP addresses not in your allowlist will be rejected with a 403 Forbidden error.The allowlist is matched exactly. CIDR ranges, wildcards and subnet masks are not supported, so every address must be listed individually. A token with an empty allowlist matches nothing and will reject every request.

Test Your Token

Verify your token and IP are configured correctly:

curl -X GET "https://public.api.live.turrisfi.com/v2/auth/test-restricted-access-token" \
  -H "x-restricted-access-token: your-restricted-access-token"

Success Response:

{
  "data": {
    "message": "If you see this message, your restricted access token is valid!"
  },
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-01-30T12:34:56.789Z"
}

The same check exists on v1 as GET /v1/auth/test-restricted-access-token. Neither version reports orgCategory: that field is only on GET /v2/auth/test-oauth, which needs a JWT.

Fallback Behavior

When both authentication headers are provided, the API uses this priority:

OAuth is attempted first
If OAuth fails and a Restricted Access Token is present, token authentication is attempted

This allows for graceful migration between authentication methods.

Error Responses

401 Unauthorized

Missing or invalid credentials:

{
  "statusCode": 401,
  "requestId": "dev-63c50377-1cfa-4d51-bce7-d187507853db",
  "errorType": "unauthorized",
  "errorMessage": ["Authentication token not provided"],
  "timestamp": "2025-01-30T09:58:12.488Z"
}

Expired JWT:

{
  "statusCode": 401,
  "requestId": "dev-1fb0b225-f24e-43ed-b602-8ec6d7d84758",
  "errorType": "unauthorized",
  "errorMessage": ["JWT token has expired"],
  "timestamp": "2025-01-30T19:36:41.467Z"
}

403 Forbidden

IP not in allowlist (Restricted Access Token only):

{
  "statusCode": 403,
  "requestId": "dev-e08550ef-5cfb-4a06-8686-5b8399ac5fc9",
  "errorType": "forbidden",
  "errorMessage": ["IP address \"192.168.1.1\" not in allowed list for token \"***-a5ed\""],
  "timestamp": "2025-01-30T03:25:32.327Z"
}

Best Practices

Store credentials securely

Use environment variables or a secrets manager
Never commit credentials to version control
Rotate credentials periodically

Implement token caching

Cache OAuth tokens for their full TTL (60 minutes)
Refresh tokens proactively before expiry
Handle token refresh failures gracefully

Handle errors gracefully

Implement retry logic for transient failures
Log authentication errors for debugging
Alert on repeated authentication failures

Start Here

API Conventions

Tools & Integrations

Support

Authentication

Authentication

Authentication Methods

Carrier and agency credentials

Carrier (upstream entity)

Agency (downstream entity)

OAuth Authentication (Recommended)

Step 1: Create API Client

Step 2: Get Access Token

Step 3: Use the Token

Token Lifecycle

Test Your Token

Restricted Access Token

Step 1: Create Token

Step 2: Use the Token

Security Model

Test Your Token

Fallback Behavior

Error Responses

401 Unauthorized

403 Forbidden

Best Practices

​Authentication

​Authentication Methods

​Carrier and agency credentials

Carrier (upstream entity)

Agency (downstream entity)

​OAuth Authentication (Recommended)

​Step 1: Create API Client

​Step 2: Get Access Token

​Step 3: Use the Token

​Token Lifecycle

​Test Your Token

​Restricted Access Token

​Step 1: Create Token

​Step 2: Use the Token

​Security Model

​Test Your Token

​Fallback Behavior

​Error Responses

​401 Unauthorized

​403 Forbidden

​Best Practices

Authentication

Authentication Methods

Carrier and agency credentials

OAuth Authentication (Recommended)

Step 1: Create API Client

Step 2: Get Access Token

Step 3: Use the Token

Token Lifecycle

Test Your Token

Restricted Access Token

Step 1: Create Token

Step 2: Use the Token

Security Model

Test Your Token

Fallback Behavior

Error Responses

401 Unauthorized

403 Forbidden

Best Practices