Discover the target system

Building a connector, step 2 of 10. Previous: Build a custom connector.

Before you declare anything, find out how the system handles identity and access, and what its API can read and change. The answers decide the kind of connector, its entities, its Grant kinds and what to leave out. Write each fact down with a link to the vendor's documentation, and mark anything you could not confirm as an assumption. These notes become your connector's README.md.

Questions to answer

Work through them in order. The last column says where each answer is used.

Question	Why it matters	Used in
Which editions or licence tiers include the APIs you need? SCIM and admin APIs are often enterprise-only.	A connector that needs a tier the customer lacks fails at install.	README, limits
What is an account: humans only, or also service accounts, bots, guests and external collaborators?	Exactly one entity is the account.	Model entities
Which lifecycle states exist (active, suspended, deactivated, invited, deleted) and which API calls move between them?	They map to Owlie's active, disabled and deleted states, and decide which of enable, disable and delete your connector supports.	Model entities
How is an account created: directly, by invitation, just in time through single sign-on, or only outside the product?	Invitation-based and externally created accounts need a declaration.	Model entities
Which identifier never changes (an opaque id), and which can change (email, username, display name)?	The first identifier is the account's identity in Owlie.	Model entities
Which other objects carry access: groups, teams, roles, workspaces, projects, organizations, licences? Do they nest?	Candidate entities and Grant kinds.	Model entities
How is access granted: membership, a role, a role scoped to a container, a permission on an object? Is there inheritance?	The mapping of each kind of access.	Model Grant kinds
For each kind of access: is there a call that lists it, one that adds it and one that removes it, and which admin role or scope does each need?	Listing decides whether it can be a Grant kind; add and remove decide whether Owlie may write it.	Model Grant kinds
Does adding an assignment replace an existing one on the same pair, or sit beside it? What does the API answer for "already a member" and for "not a member"?	Slots, and the evidence Grant writes rely on.	Model Grant kinds
Which protocol: REST, GraphQL, SCIM 2.0, LDAP, a database, file exports? Is it reachable from the internet or only on a private network?	Chooses the kind of connector.	Choose a kind
Is the base URL fixed, per tenant, per region, or returned when you sign in?	Configuration fields and the base URL.	Your track's authentication page
How does it authenticate: API key, Basic, OAuth authorization code, client credentials, a service account with a signed JWT, a private-key JWT?	The authentication options.	Your track's authentication page
How does each list call page? Is there a maximum page size, and does the API silently shorten pages? Is there a "changed since" query?	Pagination settings and incremental sync.	Your track
What are the rate limits? Are they reported with 429, or with another status such as 403 with a quota message?	Retry behavior.	Your track
Where do error codes and messages appear? Can a request fail inside a 200 response (GraphQL errors, { "ok": false })?	Error handling.	Your track
Are writes synchronous? An asynchronous bulk job cannot confirm a single change.	Whether a write can be a Grant write.	Decide what not to govern

Webhooks and event streams are not needed: Sync reads the system on a schedule.

Where to look

1. The vendor's official API reference, one page per call you plan to use. Keep the URL of each.
2. The admin or help-center documentation for the permission model: which roles exist, what they allow and how inheritance works. API references rarely explain it.
3. The vendor's SCIM documentation, if there is one, for what its SCIM does not support.
4. OpenAPI specifications and official SDKs when the prose reference is thin. They show response shapes; they do not prove behavior.
5. The vendor's changelog and deprecation notices, so you do not build on an endpoint that is being retired.

Forum answers, blog posts and remembered behavior are leads to confirm, not evidence.

Facts and assumptions

Keep two lists in your notes:

• Vendor facts: statements the official documentation makes, each with its link.
• Assumptions: anything else, such as behavior inferred from a response, an error code seen in an SDK but not documented, or a response shape you only saw in a documentation example. An assumption stays one until a test account confirms it.

Resolve these before modeling

• An access relationship with no list call. Owlie cannot read it, so it cannot be a Grant kind. At most it becomes a custom operation.
• An identifier that can change, such as an email address used as the only key. Look for an opaque id first.
• Writes that need more than reads: a higher tier, an extra scope, an admin role. Note it for each kind of access.
• A 404 that means both "not found" and "not allowed". It weakens every "already gone" answer built on a 404.
• Permissions on individual objects at unbounded scale, such as every file or record. This needs a decision in step 5 before modeling.
• Only asynchronous or bulk writes. A write you cannot confirm is not a Grant write.

Next: Model entities