Integration Builder lets you connect almost any application to Torii — even if Torii doesn't have a built-in integration for it. You define how to pull user data from an external app's API, and Torii handles syncing users, tracking licenses, and keeping everything up to date.

What you'll need: The app's API documentation, valid API credentials, and a basic understanding of how its API response is structured. The app must also expose an API endpoint that returns a list of its users, members, or employees — Integration Builder cannot work without one.

Getting Started

Accessing Integration Builder

Go to the Integrations page and click the Integration Builder tab. If you haven't created any integrations yet, click Open Integration Builder to launch the wizard and build your first one.

1. Build Your Integration

Use the wizard to configure the integration once: the API endpoint, authentication method, field mappings, and status rules. This is a one-time setup shared across all connections. See Step-by-Step: Building an Integration below for a full walkthrough.

2. Connect Your Integration

After an integration is built, it appears in the Available to Connect section of the Integration Builder tab. Connecting is a separate action from building — click the integration to open the connection dialog and supply your credentials.

The first field is Account Name — a unique label for this specific connection (e.g., "Prod" or "Dev"). You can connect the same integration more than once with different account names, for example to connect both a production and a development instance.

Important: Using the same account name twice for the same integration will overwrite the existing account's data. Always use a distinct name for each connection.

The remaining fields are the credentials configured during the build, such as an API key or token.

For information on sync frequency, error handling, and viewing your connected accounts, see Managing Your Integrations.

Step-by-Step: Building an Integration

The following example uses a fictional app called "Acme." The exact values you enter will always depend on your app's API documentation.

Step 1: General Information

Select the app from the list and enter its base API URL. You can find this in the app's API documentation.

Step 2: Authentication

Select the authentication method your app requires — check its API documentation to find out which one to use. Common options include Bearer Token, Basic Auth, Custom Headers, Query String, OAuth 2.0 (Client Credentials), and OAuth 2.0 (Authorization Code) (the authorization code flow, used when the app requires a user to grant access on its login page).

For built-in methods (such as Bearer Token or Basic Auth), the credential fields are predefined and collected at connection time. If you use Custom Headers, you define your own headers and choose for each one whether its value is Set now in the wizard (shared across all connections — for example, a static scope or version header) or Set later, provided when you connect the integration (for sensitive values like API keys or tokens).

OAuth 2.0 Auth Code

Use this when the app issues access tokens through an end-user authorization flow (the user is redirected to the provider's login page and approves access). Configure the following from your provider's OAuth documentation:

• Authorization URL — the URL the user is redirected to in order to grant access (e.g. https://api.example.com/oauth/authorize).
• Token URL — the URL Torii calls to exchange the authorization code for an access token (e.g. https://api.example.com/oauth/token).
• Scopes — the permissions Torii needs. Add each scope your integration requires; the order is preserved.
• Supports refresh token — leave this checked for most providers. Uncheck it only if your provider does not issue refresh tokens. Without a refresh token, Torii won't be able to keep the connection alive long-term, which can cause syncs to stop working.
• Advanced OAuth parameters (optional) — extra key/value parameters to send on the authorization URL, the token exchange request, or the refresh token request. Most providers don't need these. They are useful for provider-specific quirks, for example Google's access_type=offline and prompt=consent on the authorize URL to make sure a refresh token is returned.

Torii redirect URLs. When you set up the OAuth application on the provider's side, you must add Torii's redirect URLs to its allowed redirect URIs:

• A required production redirect URL — needed so customers can connect the integration in Torii.
• An optional test redirect URL — only needed if you want to test the OAuth connection from inside the builder. Most providers allow multiple redirect URIs, so you can add both.

The exact URLs to add are shown in the wizard when you select OAuth 2.0 Auth Code — copy them from there into your OAuth app configuration.

How tokens are sent: Torii sends the OAuth access token as a Bearer token in the Authorization header of API requests. Other token placements are not supported.

Step 3: Users Endpoint

Integration Builder works by calling an API endpoint that returns a list of the app's users, members, or employees. Check the app's API documentation to confirm this endpoint exists and find its path. If it doesn't exist, Integration Builder cannot be used with that app.

Enter the endpoint path and, if the API is paginated, configure the pagination settings so Torii fetches all users — not just the first page. Several pagination styles are supported — offset/limit, page number, next URL (follow a link to the next page), and query-string token — so pick the one your API uses and fill in its parameters.

You'll also need to specify the response path — the location within the API response where the list of users is found. API responses don't always return the array at the root level; it's often nested under a key such as data or a deeper, dot-notation path like users.values. Enter that path so Torii can locate and process the array of user objects — and leave it empty if the response itself is the array. You can verify the structure by running the test in the next step.

Step 4: Test the Connection

Enter your credentials and run the test. Torii calls the API and displays a sample of the actual response, letting you see the real field names you'll map in the next step.

Testing OAuth 2.0 Auth Code integrations. For the authorization code flow, you'll first authorize a test session before running the API test:

• Enter a test Client ID and Client Secret. These are used only for this test session — they are never saved to the integration.
• Make sure the test redirect URL shown in the panel is added to your OAuth app's allowed redirect URIs (it's different from the production redirect URL used for real connections).
• Click Authorize & continue. A popup opens the provider's login page, you grant access, and Torii exchanges the authorization code for an access token. The token is held in memory only for this session and is shown with a live expiry countdown — you can re-authorize or clear it at any time.
• Once authorized, run the API test as usual to verify the users endpoint and response structure.

Note: Running the test does not connect the integration. After saving, you'll still need to connect it separately from the Integration Builder tab.

Step 5: Map Fields

Map the API's field names to Torii's user attributes using the field names from your test response or API documentation. If you ran the test, a live preview shows how each user's data will appear in Torii as you configure your mappings. If your organization has custom user attributes for this app, you can also map them — see Custom Fields below.

Field Mappings

Two fields are required:

• External ID — a unique identifier for each user in the app
• Email — the user's email address

Make sure the values your API returns for these fields are valid. Invalid or missing values in External ID or Email may cause Torii to filter out those users.

The remaining fields are optional: Username, Full name (or First name + Last name separately), Role, Creation time, and Last Visit Time.

Condition Operators

Three sections below — Torii Calculated Status, Status in App (Conditions mode), and License Status (Conditions mode) — let you build rules against the API response. Each row picks an operator from a dropdown:

• is / is not — exact match on the API value (e.g. status is active).
• any of — match against a comma-separated list of values (e.g. role any of admin, owner).
• contains / not contains — substring match on a text value.
• ≥ — numeric comparison; treats the API value as a number.
• has value — true whenever the field is present and not empty. No value to enter.
• some (array contains) — for fields whose API value is an array of objects. Pick the array path, then add one or more nested rules; the row matches when at least one item in the array satisfies all of them. For example, set the path to licenses, choose some (array contains), and add nested rules such as plan is enterprise and active is true.

Multiple condition rows in the same group still combine with AND — every row must match. Only some (array contains) introduces nested conditions; the other operators are a single field/value comparison.

Torii Calculated Status

Define conditions to determine which users are considered active:

• Active users will appear under "Users with access" in Torii.
• Users who don't match will be marked as deleted and appear under "Users with and without access."

All conditions must match for a user to be considered active (AND logic). If no conditions are set, all users returned by the API are treated as active.

Status in App

The human-readable status label shown in Torii. Three configuration options:

• Auto — derived from Torii Calculated Status: active → "Active," inactive → "Deleted." Best for most cases.
• Field — pulled directly from a single API field that already contains readable values (e.g., "Active," "Suspended," "Deactivated").
• Conditions — custom if/else rules for when the API returns codes or numbers that need translating into readable labels. Each branch uses AND logic — all rules in a branch must match.

If you use Conditions for Status in App, make sure the logic aligns with your Torii Calculated Status rules — otherwise the two may appear contradictory in Torii.

License Status

License Status tells Torii which license a user holds — powering license tracking, spend analysis, and user-level reporting.

Auto Mode

License follows Torii Calculated Status: active users get an active license, inactive users get a deleted license. You can optionally provide a license name; if left blank, Torii uses the app's name. Use this when all users share the same license type.

Conditions Mode

Define multiple licenses and assign them based on user data. For each license, specify a name and match conditions (e.g., a plan field equals enterprise). Each branch uses AND logic — all conditions in a branch must match.

A user can match more than one license — Torii records all matching names. Users who don't match any condition are still synced but won't have a license assigned. Consider adding a catch-all license as the last entry to cover any unexpected user types.

Custom Fields

If your organization has defined custom user attributes for this app (for example "Department," "Cost Center," or "Employee ID"), they appear at the bottom of the mapping step in a Custom Fields section. Map each one by entering the path to the matching field in the API response — the same way you map built-in attributes like Email or Role.

Custom fields are defined at the organization level, not in the wizard. The list is read-only and scoped to the selected app: switching apps in Step 1 reloads the relevant set. If the app has no custom fields configured, the section shows a "no custom fields" message. To add new custom fields, contact Torii Support.

Each row shows the field name, an input for the response path, and the field's expected type. Supported types are Text, Number, Email, Date, Multi-value string, and User. Mapping is optional — fields you leave blank are simply skipped during sync.

The live preview validates each mapped value against its type. Path resolution failures or type mismatches (for example, text written into a Number field) are flagged inline so you can fix them before saving. Users are not dropped because of an invalid custom field — only the problematic field is omitted from the synced record.

Step 6: Review and Save

Review the summary to confirm everything looks correct, then save. The integration is now built and will appear in the Available to Connect section of the Integration Builder tab.

Managing Your Integrations

Viewing Connected Accounts

Connected accounts appear in two places:

• Integration Builder tab → Your Connected Integrations section
• All Integrations page → Your Builder Integrations section

Sync Schedule

Torii syncs data from connected integrations once daily.

Errors

If a sync fails, Torii surfaces the error returned by the external API — authentication failures, permission errors, and so on.

• 400–404 errors — Torii disables the integration and notifies admins to review the connection credentials or configuration.
• Other errors — Torii displays the error in the UI and retries automatically on the next daily sync.