baton-sdk. It reads access data from one system and reports it to C1 as resources, entitlements, and grants. The SDK handles orchestration, pagination coordination, output format, and communication with C1, so you only translate your system’s API into the Baton model.
Your connector answers three questions:
- What exists? Users, groups, roles, applications.
- What permissions are available? Entitlements that can be granted.
- Who has what? Grants that connect users to entitlements.
ResourceSyncerV2, the interface that current connectors such as baton-demo, baton-github, and baton-okta implement. The older ResourceSyncer interface still works. See V1 syncer differences if you maintain a connector that uses it.
Start a connector
Start from the Baton Starter Pack, a GitHub template repository that creates a connector project with the standard layout, Makefile, CI workflows, and configuration scaffolding.1
Create your repository from the template
On the Starter Pack page, select Use this template, and create a repository named
baton-{service}, for example baton-acme.2
Allow workflow write access
In your new repository, go to Settings > Actions > General and set Workflow permissions to Read and write permissions. You can revert this setting after the repository initializes.
3
Update cookiecutter.json
Set
repo_owner, repo_name, and name to match your repository, then commit the change. A GitHub Actions workflow initializes the project.The Starter Pack’s generated stubs use the V1
ResourceSyncer method signatures. To use the V2 form in this guide, change each builder’s method signatures and make ResourceSyncers return []connectorbuilder.ResourceSyncerV2.Project layout
Makefile targets
Define configuration
Declare the fields your connector needs inpkg/config/config.go. Mark credentials with field.WithIsSecret(true) so the SDK treats them as secrets.
make generate to produce conf.gen.go, a struct with one typed field per configuration field. For example, api-key becomes ApiKey. Define at least one field before you generate, because the generator panics on an empty schema.
Wire up the entry point
main.go passes your configuration and a constructor to the SDK, which adds the standard command-line flags and runs your connector:
config is github.com/conductorone/baton-sdk/pkg/config, and cfg is your pkg/config package. RunConnector replaces DefineConfiguration, which the SDK now marks deprecated. The Starter Pack’s main.go still uses DefineConfiguration, and both work.
Register your resource builders
connector.go defines the connector itself. It implements ConnectorBuilderV2: a Metadata method, a Validate method that exercises your credentials, and a ResourceSyncers method that returns one builder per resource type.
cli is github.com/conductorone/baton-sdk/pkg/cli. The generated configuration type is named after the string you pass to config.Generate in gen/gen.go. For example, config.Generate("acme", cfg.Config) produces a type named Acme.
Implement ResourceSyncerV2
Per resource type, implement four methods:
The paged methods return
([]T, *resource.SyncOpResults, error). Set NextPageToken on the results to ask for another page, or return nil results to finish. The opts argument is a resource.SyncOpAttrs: opts.PageToken.Token holds the token you returned on the previous call, and opts.PageToken.Size holds the page size the SDK requests. See Pagination patterns for token handling beyond a single cursor.
ResourceType
A resource type describes a kind of resource and the traits that tell C1 how to interpret it. Declare each type once and return it from the builder:TRAIT_USER for people, TRAIT_GROUP for collections, and TRAIT_ROLE for permission bundles. See Core concepts for the full list.
List
List returns the resources of this type. Create resources with the constructors in pkg/types/resource. For user, group, and role resources, the fourth argument is a slice of trait options, and the options after it are general resource options:
NextPageToken means you’re done. The SDK calls List again until you return an empty token.
The RawId annotation
Add aRawId annotation with the identifier that the source system’s own API uses for the resource, as shown in the previous example. The table lists typical values:
See ID correlation recipes for when a resource needs a
RawId and how to build one for types such as Databricks groups, whose RawId is not the native ID. Pass the annotation as a resource option. WithAnnotation is a package function, not a method on the resource.
Entitlements
Entitlements returns the permissions a resource offers. Use the helpers in pkg/types/entitlement instead of building the proto by hand, because they generate the entitlement IDs that grants must match:
WithGrantableTo states which resource types can receive the entitlement. NewAssignmentEntitlement fits membership, NewPermissionEntitlement fits permissions such as read or write, and NewOwnershipEntitlement fits ownership.
Users usually offer no entitlements, because they receive grants. Mark the user resource type with the SkipEntitlementsAndGrants annotation, so the SDK skips both calls for it:
Grants
Grants reports who holds each entitlement on a resource. NewGrant takes the resource that offers the entitlement, the entitlement’s slug, and the principal that holds it:
Id you gave the type in ResourceType. If it doesn’t, the grant points at a resource that doesn’t exist.
The SDK fails the sync if a page returns the same non-empty token it received. Make sure each token you return moves the sync forward.
Modeling decisions
How you structure resources and entitlements determines what C1 can manage.What to sync as a resource
Entitlement granularity
- Fine-grained: Separate entitlements for read, write, and admin give you more control in access reviews, at the cost of more grants to manage.
- Coarse-grained: A single “access” entitlement is simpler, but you can’t revoke admin without revoking everything.
Parent-child relationships
Some systems have hierarchies, such as organization, project, and resource. The parent declares the child types it contains, and each child names its parent:ChildResourceType annotation, the SDK never lists the children. Use hierarchies when child resources only make sense within a parent, when you need to scope List calls to a parent, or when the target API is organized that way. See Pagination patterns for paging through hierarchical data.
Generate the capability manifest
The capability manifest declares which operations each resource type supports. Don’t write it by hand. Generate it from the connector binary:connectorrunner.WithDefaultCapabilitiesConnectorBuilderV2 in your RunConnector options.
The
Capability enum in connector.proto has the full list.
Test your connector
A connector is ready when:- Sync is deterministic. The same inputs produce stable IDs and consistent results across runs.
- Pagination works. No token loops, and large datasets complete.
- You can run it without production C1 credentials. The connector runs locally and writes a sync file.
baton CLI:
Common mistakes
Resource type mismatches
A grant references its principal byResourceId (type and ID). If the principal’s type doesn’t match the Id you declared in ResourceType, the grant points at nothing.
Implicit capability claims
A connector can accept a--provisioning flag and still not implement any provisioners. Treat the flag as necessary, not sufficient.
API clients
If the service has an official Go SDK, use it. Otherwise, the SDK’suhttp package builds an HTTP client that works with the SDK’s retry behavior:
uhttp doesn’t retry requests itself. It translates HTTP statuses such as 429, 502, 503, and 504 into gRPC Unavailable errors, and the SDK retries calls that fail with Unavailable or DeadlineExceeded. Errors with any other code stop the sync. uhttp also caches successful GET responses.
Error handling
Return errors and don’t panic. Wrap them with context:Credentials
Never log credentials. Declare credential fields withfield.WithIsSecret(true), as in Define configuration.
Quick reference
Common traits
See Core concepts for the complete list.
SDK helpers
V1 syncer differences
The V1ResourceSyncer interface has the same four methods. Its paged methods take a *pagination.Token and return the next page token as a string with an annotations.Annotations value, and ConnectorBuilder.ResourceSyncers returns []connectorbuilder.ResourceSyncer:
SyncOpAttrs.Session, but only when the connector enables it with connectorrunner.WithSessionStoreEnabled().