The access graph
Your connector produces an access graph that C1 uses for access reviews, provisioning workflows, and reporting. The graph has three node and edge types:- Resources are things that exist: users, groups, apps, roles, projects, and so on.
- Entitlements are permissions you can assign on a resource: member, admin, read, and so on.
- Grants are facts that connect a principal to an entitlement: Alice is a member of Engineering.
Hierarchical resources
Most access management systems flatten everything into one list. Baton lets resources have parent-child relationships, which preserves the natural structure of your target systems. Consider GitHub, where organizations contain repositories, or AWS, where accounts contain services and services contain resources. When your connector models these hierarchies, C1 can:- Show access in context: this role applies to this project, not globally.
- Run scoped access reviews, such as reviewing all access within one organizational unit.
- Support inheritance where the target system has it.
- The parent resource carries a
ChildResourceTypeannotation for each child type it contains. - Each child resource sets its parent with
WithParentResourceID.
List with no parent to get the top-level resources. It then calls List for each child type of each parent that declares one, and passes the parent’s ResourceId so you can scope your API call. You describe the structure, and the SDK walks it. See Modeling hierarchies for examples.
Resource types and traits
Every resource has a resource type, identified by a string ID. A resource type can declare traits that tell C1 how to interpret its resources. Traits let C1 understand what kind of thing a resource is, even when different systems call it different names.
Traits are optional for custom resource types, but they unlock features. When you mark a resource with
TRAIT_USER, C1 can treat it as a user: show it in user-centric views and apply user-specific policies.
Entitlements
Entitlements define what can be granted. They attach to a resource, because permissions belong to something specific.Id by hand.
Entitlement purpose
Each entitlement has a purpose that tells C1 how to interpret it. The constructor you use sets the purpose:Grants
Grants record who has what. A grant connects a principal, usually a user, to an entitlement:NewGrant takes the resource that offers the entitlement, the entitlement’s slug, and the principal, which is either a *v2.Resource or a *v2.ResourceId. It builds the entitlement ID and the grant ID for you. A grant must have an ID, so don’t construct v2.Grant values by hand.
The sync lifecycle
The SDK orchestrates the sync, and you implement the callbacks. For each resource type, the work has four parts:- Define the type (
ResourceType). - List the instances (
List). - For each resource, list its entitlements (
Entitlements). - For each resource, list its grants (
Grants).
--workers flag. A sync can also resume from a checkpoint in a new process, so don’t assume that anything you cached in memory during List is still there when Grants runs.
The SDK fails the sync when a page returns the same non-empty token it received. It doesn’t detect longer loops, such as a token that alternates between two values.
The sync pipeline
When a connector runs, data flows through these stages:- Fetch. Your connector calls the external API.
- Transform. Your connector creates resource, entitlement, and grant objects.
- Output. The SDK writes the objects to a
.c1zfile. - Ingest. C1 reads the
.c1zfile and updates its model of access.
.c1z file is a zstd-compressed archive of the sync data. The current format stores a Pebble checkpoint. Inspect a file with the baton CLI. The current SDK can’t read the older SQLite-based format, and it tells you to convert such a file with baton to-pebble.
Resource identifiers
During a sync, the SDK identifies a resource by itsResourceId: the resource type ID plus the resource ID you passed to the constructor. Choose a stable, unique value for the resource ID, such as the source system’s native identifier, so the same resource gets the same ID on every sync.
You can also attach a RawId annotation, which records the identifier that the source system’s own API uses for the resource:
RawId. See ID correlation recipes for when to set it and which value to use. Don’t set ExternalId on resources, because the SDK marks it deprecated and no longer uses it.
Modeling decisions
Your modeling choices expand or constrain what your organization can do with access control. Two connectors can both be correct and still give very different experiences in C1:- Entitlement granularity.
- Fine-grained entitlements (read, write, admin) give you more precision in reviews and provisioning, at the cost of more grants and API calls.
- Coarse-grained entitlements (access or no access) are simpler, but you can’t request or revoke specific privilege levels.
- Capability surface. A connector can sync only, or sync and provision (grant, revoke, create, and delete). Check each connector and version instead of assuming.
Model what matters for access decisions. If you need to revoke admin access separately from read access, make them separate entitlements.
Constraints and guardrails
The SDK includes guardrails that catch common mistakes early:- Pagination. The next token must change, or the sync fails.
- Traits. A resource must carry the trait that its resource type declares.
- Skipping work. Resource types that never have entitlements or grants, such as users in many systems, can carry the
SkipEntitlementsAndGrantsannotation so the SDK doesn’t call those methods.SkipEntitlementsandSkipGrantsskip one of the two. - Optional advanced behavior. Targeted sync (
Get), account creation, resource deletion, and credential rotation aren’t universal. Start with the basics and add them when you need them.
Error handling
If an API call fails, return an error. The SDK retries a failed call only when it returns a gRPCUnavailable or DeadlineExceeded status. Any other error stops the sync. The uhttp package translates HTTP statuses such as 429, 502, 503, and 504 into Unavailable for you, so use it for API calls. Permanent failures, such as bad credentials or missing permissions, should surface as errors that explain the cause.
Rate limiting
Most APIs have rate limits. Theuhttp package can read an API’s rate limit headers when you pass the request option for them, and it can limit your request rate on the client side when you enable that. Neither happens by default, so check the uhttp options when your API enforces strict limits. Smaller pages mean more requests, so choose page sizes with your limits in mind.
Execution modes
Connectors can run in different modes:
Daemon mode needs both the client ID and the client secret, and the connector exits with an error if either is missing. On Windows, a connector that runs as a Windows service always runs in daemon mode.
See Deployment for operational details on each mode.