Bridge API Overview
Build custom connectors to sync external applications with Iden using the Bridge REST API.
The Bridge API is a REST protocol that lets you build connectors for applications that do not have a native Iden integration. Your connector registers an application, defines its resource types, pushes resource data through paginated sync sessions, and executes provisioning tasks on behalf of Iden.
Who is this for?
This guide is for developers building connectors that integrate external applications (internal tools, niche SaaS products, custom HR systems, etc.) with the Iden identity governance platform. You should be comfortable making REST API calls and handling JSON payloads.
Core Concepts
Bridge Apps
A Bridge app represents an external application managed via the Bridge protocol. Multiple apps can share resource type definitions via the clone_from parameter.
Resource Types
Resource types define what kind of data your connector syncs. Each type maps to one of three base types:
| Bridge Type | Description |
|---|---|
account | User accounts in the external system |
group | Groups, teams, or roles |
license | Software licenses or entitlements |
When you register a group or license type, Iden automatically creates a companion type to track memberships and assignments.
Sync Sessions
Syncing follows a session-based, paginated protocol with PUT semantics:
- Start a sync session (returns a
sync_id). - Push one or more pages of records per resource type (up to 100 records per page).
- Complete the session -- records not included in any pushed page are marked as removed.
Alternatively, you can abandon a session to skip the removal step while keeping already-pushed records.
Tasks
Tasks are provisioning actions (create account, suspend account, reset password, etc.) that Iden schedules for your connector to execute. Your connector polls for pending tasks, performs the action in the external system, and reports back success or failure.
High-Level Workflow
1. Create app POST /api/v1/bridge/apps/
|
2. Register types POST /api/v1/bridge/apps/{app_id}/resource-types/
|
3. Sync resources POST .../sync/ -> PUT .../sync/{id}/{slug}/ -> POST .../complete/
|
4. Execute tasks GET .../tasks/?status=pending -> PATCH .../tasks/{id}/status/Guides
Getting Started
Step-by-step walkthrough: create an app, register resource types, and run your first sync.
Sync Guide
Deep dive into the paginated sync protocol, ordering rules, and cleanup behavior.
Task Execution
Poll for provisioning tasks, execute them, and report results back to Iden.
Cloning Apps
Share resource types across multiple Bridge apps using clone_from.
Error Reference
Complete list of error codes, HTTP statuses, and troubleshooting tips.
API Reference
For the full auto-generated endpoint reference, see the Bridge API Reference.