Overview

The API settings page is where your engineering team generates the credentials that connect Turris to your own systems. It supports two credential types: API Clients, which use the OAuth 2.0 client-credentials flow for secure backend-to-backend integrations, and Restricted Access Tokens, a fallback for front-end apps that have no backend of their own.

What is the API Settings Page?

The API settings page is the single place to provision, view, and retire the credentials your developers use to call the Turris public API. From here you generate Client IDs and secrets, control which browser origins or IP addresses are allowed to use those credentials, and jump straight to the developer documentation when you need it.

Who uses it. Developers, engineering leads, and administrators at carriers, MGAs, and wholesalers who are wiring Turris into their internal systems (a policy admin platform, a data warehouse loader, an in-house automation script, a partner portal, and so on). The page lives under the Developer group in Settings. Creating an API Client additionally requires the Admin or Developer role, so non-technical members can open the page but cannot generate that credential type.

What it lets you do:

Generate an API Client with a Client ID and Client Secret so a server-side integration can exchange them for short-lived access tokens.
Generate a Restricted Access Token for a browser-only app that needs to read a limited subset of Turris data without a backend of its own.
Lock an API Client to a specific list of browser origins so requests from anywhere else fail the Turris CORS check.
Lock a Restricted Access Token to a list of allowed IP addresses so requests from anywhere else are rejected.
Identify each credential at a glance from a four-character preview of the secret or token, even though the full value is revealed only once, at creation.
Open the Turris public API documentation and the Turris Postman workspace in one click for hands-on exploration.

Accessing the API Settings Page

In the left sidebar, click Settings (at the bottom of the navigation). The Settings modal opens.
In the modal's left navigation, scroll to the Developer group and click API.
The page opens with a Configure your API information banner. If your role allows creating credentials, the View Docs and Run in Postman buttons appear at the top, with the Add New dropdown beside them. Below that, the API Clients and Restricted Access Tokens tables list any existing credentials.

Note: You can also reach the page directly by appending ?settings-modal=open&path=api to any upstream URL.

What's visible on the page:

Element	Description
Configure your API banner	Reminder that the recommended access point is an API Client using the secure OAuth flow, and that Restricted Access Tokens are for front-end apps without a native backend.
View Docs button	Opens the Turris public API documentation site (`docs.turrisfi.com`) in a new tab. Shown only to users who can create credentials.
Run in Postman button	Opens the Turris Postman workspace in a new tab so you can import the collection and start firing requests. Shown only to users who can create credentials.
Add New dropdown	Shown only to users who can create credentials. Reveals two options: API Client (Create a secure API client) and Restricted Access Token (Create a restricted access token).
API Clients table	Lists every API Client in your organization. Hidden until at least one API Client exists.
Restricted Access Tokens table	Lists every Restricted Access Token in your organization. Hidden until at least one token exists.

To inspect or manage an individual credential, click anywhere on its row. A slide-over opens with the editable fields and, for existing credentials, a Delete button.

Note: The View Docs and Run in Postman buttons and the Add New dropdown all require permission to create credentials. A read-only member sees only the banner and the tables.

API Clients table columns

Column	Description
Name	The display name you gave the API Client when creating it.
Description	Optional free-text description. Renders as `-` when empty.
Client ID	The public identifier for this integration. Click the value to copy it to your clipboard.
Client Secret	Shows the last four characters as `•••• XXXX`. The full secret is displayed only once, in the confirmation modal that appears right after creation.
Allowed Origins	Pill list of every browser origin permitted to call the Turris API with this client. Renders as `-` when no origins are configured. A hover hint notes these origins pass the Turris API's CORS restrictions.
Status	`active` shows in green; any other value shows in red.

Restricted Access Tokens table columns

Column	Description
Name	The display name you gave the token.
Token	Shows the last four characters as `•••• XXXX`. A hover hint explains that only the last four characters are revealed, the rest cannot be retrieved, and a lost token must be deleted and recreated.
Allowed IPs	Pill list of every IP address permitted to use the token. Renders as `-` when none are configured.

Note: Both tables stay hidden until you create your first credential of that type. Once a credential exists, the table renders for everyone who can view the API settings page.

Creating an API Client

When you'd do this. You are wiring a backend service (your in-house policy admin system, your data warehouse loader, an internal automation script, and so on) to the Turris public API, and you need a long-lived Client ID and Client Secret to authenticate.

Click Add New at the top of the page and choose API Client.
The Add API Client slide-over opens. Fill in the fields:

Field	Required	Description
Client Name	Yes	Short, human-readable label so teammates can identify the integration. Example: `Internal CRM Sync`, `Data Warehouse ETL`.
Description	No	Free-text note describing what the client does or which system it belongs to.
Allowed Origins	No	Comma-separated list of browser origins permitted to call the Turris API with this client. Example: `https://example1.com, https://example2.com`. Leave blank when the client is only used from a backend.

Click Add. A confirmation modal titled API Client Created opens, displaying the newly issued Client ID and Client Secret.
Click each value to copy it, then store both immediately in your secrets manager. The Client Secret will never be shown in Turris again.
Click Ok to close the modal. The new API Client now appears in the API Clients table with its Status set to active and its Client Secret column showing only the last four characters.

Warning: The Client Secret is displayed exactly once. If you close the modal before copying it, you must delete the API Client and create a new one. Never paste the Client Secret into browser code, a public repository, or a mobile app bundle. It belongs in a secrets manager that only your server-side code can read.

Note: Only users who hold the Admin or Developer role can submit the form. Other users can open the slide-over to inspect the fields, but the inputs and the Add button stay disabled.

How the OAuth Flow Works

Your backend sends the Client ID and Client Secret to the Turris Get Token endpoint.
Turris returns a JWT (access token) with a 60-minute lifetime.
Cache the JWT in your backend and attach it as a Bearer token on subsequent calls to protected Turris endpoints.
When the JWT expires, your backend exchanges the Client ID and Client Secret again to get a fresh JWT.
If a browser needs Turris data, use the Backend-for-Frontend (BFF) pattern: the browser calls your own backend, and your backend attaches the cached JWT before forwarding the request to Turris.

Creating a Restricted Access Token

When you'd do this. You have a front-end application (a partner portal, an internal dashboard, a customer self-service page) that needs to read a limited subset of Turris data, and there is no backend you can route requests through. The token authenticates the request, and the IP allow-list keeps anyone outside your environment from using it.

Click Add New at the top of the page and choose Restricted Access Token.
The Add Restricted Access Token slide-over opens. Fill in the fields:

Field	Required	Description
Token Name	Yes	Short, human-readable label so teammates can identify the token. Example: `Partner Portal Read-Only`.
Allowed IP Addresses	Yes	Comma-separated list of IP addresses permitted to use this token. Example: `203.0.113.1, 203.0.113.2`. Requests from any other IP address are rejected. At least one address is required.

Click Add. A confirmation modal titled Restricted Access Token Created opens, displaying the newly issued token.
Click the value to copy it and store the token somewhere safe. The full value will never be shown in Turris again.
Click Ok to close the modal. The new token now appears in the Restricted Access Tokens table with its Token column showing only the last four characters.

Warning: Restricted Access Tokens reach only a small subset of API endpoints by design. If your integration needs broader coverage, use an API Client instead.

Tip: Even though IP allow-listing is the main security boundary, treat the token itself as a secret. Do not commit it to source control, paste it into screenshots, or share it in public chat channels.

Updating or Deleting a Credential

When you'd do this. You want to add or remove an allowed origin or IP, rename a credential, change its description, or retire a credential that is no longer in use.

In either table, click the row for the credential you want to manage. The slide-over opens prepopulated with the current values.
Edit any of the fields you want to change:
- API Client: Client Name, Description, Allowed Origins.
- Restricted Access Token: Token Name, Allowed IP Addresses.
Click Update to save your changes. A success alert confirms the change.
To retire the credential, click Delete. A confirmation modal appears showing the credential's name. Click Delete in the modal to confirm. The credential is removed immediately.

Note: You cannot view or regenerate the original secret or token from this slide-over. Editing a credential only changes the metadata around it. To rotate the underlying secret, delete the credential and create a new one.

Note: Editing or deleting an API Client requires the Admin or Developer role; for users without it, the fields and the Update / Delete buttons stay disabled. Restricted Access Tokens have no role restriction beyond the permission to manage credentials.

Warning: Deletion takes effect immediately and cannot be undone. Any integration still using the credential will start getting authentication failures the moment you confirm.

Filtering and Searching

This page has no filter dropdowns or search box. Credential lists are kept short by design, so both tables simply render every credential in your organization, sorted alphabetically by Name. To find a specific credential, scan the Name column; to confirm which credential a system is using, match the last four characters shown in the Client Secret or Token column.

Status Indicators

Only the API Clients table shows a status. Restricted Access Tokens have no status column: once created, a token stays valid until it is deleted from this page.

Color	Label	Meaning	What to do about it
Green	`active`	The API Client is enabled and can exchange its Client Secret for an access token.	Nothing. The credential is healthy.
Red	Any non-`active` value	The API Client cannot be used to obtain new tokens.	Decide whether the credential should stay in service. If yes, contact support to have it re-enabled. If no, delete it and remove it from your integration.

Developer Documentation Shortcuts

Two buttons at the top of the page link out to external developer resources (shown only to users who can create credentials):

View Docs opens the Turris public API documentation at docs.turrisfi.com. Use this to look up endpoints, request shapes, response schemas, and error codes.
Run in Postman opens the Turris Postman workspace. Use this to import a ready-made collection of API requests you can run against your credentials.

Roles and Permissions

Members who lack permission to create credentials see only the Configure your API banner and the credential tables. The View Docs, Run in Postman, and Add New controls are hidden from them.
Creating, editing, or deleting an API Client additionally requires the Admin or Developer role. A member with create permission but neither role can open the Add API Client slide-over, but the form fields and the Add button stay disabled.
Creating, editing, or deleting a Restricted Access Token does not require the Admin or Developer role; the permission to manage API credentials is enough.

Frequently Asked Questions

Should I use an API Client or a Restricted Access Token? Use an API Client whenever you have a backend you can route requests through. Restricted Access Tokens are a fallback for browser-only apps and reach only a small subset of endpoints.

Why can I only see the last four characters of my Client Secret or token? The full value is stored hashed and cannot be retrieved after creation. Only the last four characters are kept in readable form, so you can tell which credential is which without exposing the secret anywhere on screen.

What happens if I lose the Client Secret or token? You must delete the credential and create a new one. There is no way to recover or reset the original value.

Why is my API request returning a CORS error? The Turris API only accepts browser requests whose Origin header is in the API Client's Allowed Origins list. Open the API Client in the slide-over, add the origin, click Update, and retry the request.

Why is my Restricted Access Token returning a forbidden error? The request either came from an IP address that is not in the token's Allowed IP Addresses list, or the endpoint you are calling is not part of the restricted subset. Verify both before contacting support.

How long does the access token from the OAuth flow last? The JWT issued by the Get Token endpoint lasts 60 minutes. Cache it in your backend and refresh it just before it expires rather than on every request.

Can I open the API Client slide-over even though my role does not allow editing? Yes. The slide-over opens for any user who can see the page, but the inputs and the Add or Update button stay disabled unless the user holds the Admin or Developer role.

Why don't I see the API page in Settings at all? API access is a premium capability under the Developer group. If your plan or role does not include it, the entry will not appear in the Settings sidebar.

Best Practices

Use API Clients for production integrations. Short-lived JWTs from the OAuth flow are safer than long-lived static tokens. Reserve Restricted Access Tokens for browser-only apps that have no backend.
Always set Allowed Origins on API Clients used from a browser. Without origin restrictions, any web page can attempt to use your Client ID once it has been observed in network traffic.
Always set Allowed IP Addresses on Restricted Access Tokens. The IP allow-list is the primary security boundary this credential type provides.
Store secrets in a dedicated secret manager. Never commit them to source control, an environment file checked into a repository, or a CI variable that is logged to the build output.
Create one credential per integration. Separating credentials by integration lets you rotate, audit, and revoke access without breaking unrelated systems.
Give each credential a clear name and description. Teammates should be able to tell what each credential is for without reading the surrounding code.
Rotate credentials periodically. Delete and recreate them on a schedule, and always rotate after someone with access to the secret leaves the organization.
Cache JWTs in your backend. Refresh them just before the 60-minute lifetime expires rather than calling the Get Token endpoint on every request.

Settings: Products & Compliance — Define products and the state-by-state license and appointment rules that govern who can sell them.
Settings: Business Rules — Set organization-wide defaults for coverage, onboarding automation, screening, and compliance verdicts.
Settings: Security — Tighten organization-wide sign-in, including SMS one-time-password MFA.
Settings: Email Domain — Register a custom sending domain so platform emails come from your own brand.
Settings: Integrations — Connect Turris to third-party tools like HubSpot so agency and contact data stays in sync.
Settings: Webhook — Register HTTPS endpoints that receive automated notifications when key compliance events occur.
Settings: Template Agreements — Keep a library of producer agreement templates used when inviting agencies.
Settings: Personal Notifications — Choose which events trigger an email or in-app alert for each user.
Users (Settings) — Add, edit, and remove members in your organization and assign their roles.
Agency Onboarding: Upload Documents — Choose which compliance documents invited agencies must upload during onboarding.
Agency Onboarding Settings: Product and State Selections — Toggle whether invited agencies pick distribution authority and operating states during onboarding.
Agency Onboarding: Payment Details — Decide whether invited agencies must provide banking details before finishing onboarding.
Agency Onboarding: Custom Questions — Build a custom onboarding step with a drag-and-drop question builder.
Agency Onboarding: Pre-Contract Review — Add a manual review checkpoint before the producer agreement is sent for signature.

Notes

OAuth client-credentials hardening

The OAuth 2.0 client-credentials flow used by API Clients is exclusively for machine-to-machine traffic. Both the Client Secret and the resulting JWT MUST stay on your backend.
Never embed the Client Secret, the JWT, or any header derived from them in browser code, mobile app bundles, or public repositories.
When a frontend needs Turris data, use the Backend-for-Frontend (BFF) pattern: the browser calls your own backend, and your backend attaches the cached JWT before forwarding the request to Turris.
For browser-side use cases without a backend, use Restricted Access Tokens instead — they're designed for that, with IP allow-listing and a limited endpoint surface.