Build a custom connector
Building a connector, step 1 of 10.
A connector teaches Owlie one kind of system: which objects exist there, how access is granted there, how to sign in, and the operations that read and change it. Owlie's catalog connectors are built the same way as the ones you build, in the same format. This section takes you from an unfamiliar system to a published, installed connector. Follow it page by page with the Next link at the bottom of each page; it splits once, where you choose the kind of connector.
When to build one
Build a custom connector when the system you need is not in the integration catalog, or when a catalog connector does not model something you need to govern. If a catalog connector is close, you can fork it in the Connector Builder instead of starting from nothing. For an HTTP connector you can also ask Owlie to build it from the vendor's documentation.
How a connector works
A connector is a declaration plus operations:
- The declaration says what the connector is, where it may run, how it authenticates, what an install configures, which objects exist in the system (entities, one of which is the account) and how access works there (Grant kinds, in terms of the unified access model). For most kinds you write a short definition and Owlie derives the full declaration from it.
- The operations list and read entities, create and change accounts, and add and remove Grants.
Owlie does everything else. It installs the connector as an integration, runs Sync on a schedule, links accounts to identities, decides from policies, requests and reviews which access should exist, calls your operations to make the system match, retries, rate-limits and records an audit trail. A connector knows only its system.
The steps
- Overview (this page).
- Discover the target system: research its identity model, API and sign-in.
- Model entities: decide which objects Owlie tracks and which is the account.
- Model Grant kinds: map each kind of access onto OUAM and decide what Owlie may write.
- Decide what not to govern: leave out what is not access, does not scale or cannot be written safely.
- Choose a kind: HTTP, LDAP, SCIM, SQL or flat file.
- Build it, following the track for your kind.
- Test your connector.
- Publish, install and upgrade.
- Maintain it.
Steps 2 to 5 are design. Do not start writing operations until you have the table of entities and Grant kinds that step 4 produces; it is the design everything else implements.
Every step that happens in the product shows two ways to do it: in the Connector Builder (Admin > Integrations > Connectors), and through the API for scripts and AI agents. Build with the API and agents collects the API operations in one place. Complete example connectors are in Examples, and every field is in the Reference.
Rules that apply throughout
- Work from the vendor's documentation. Every claim about the system's behavior should come from its official API reference or admin documentation. Write down anything you could not confirm as an assumption.
- Never invent credentials, vendor behavior or test results. If the documentation does not say what the API answers, find out on a test account before relying on it.
- Build against a test account. Every test run in the Connector Builder calls the real system. Use a sandbox or test tenant of the vendor while you build, not your production tenant.
- Model what you would govern, not everything the API exposes. Step 5 explains how to decide.
- Do not bend the access model. If a kind of access does not fit OUAM, leave it out rather than forcing it.
- A remove that reports success while the access remains is the worst failure a connector can have. The rules for writing Grants are strict for that reason.
- No secrets or customer-specific values in the connector. Credentials belong in the install's configuration, and new accounts get their email from the identity, never from a hard-coded domain.