Skip to main content
A connector is a Go program built on 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:
  1. What exists? Users, groups, roles, applications.
  2. What permissions are available? Entitlements that can be granted.
  3. Who has what? Grants that connect users to entitlements.
You implement one interface per resource type. This guide uses 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

Not every connector follows this layout exactly. Use it as a starting point.

Makefile targets

Define configuration

Declare the fields your connector needs in pkg/config/config.go. Mark credentials with field.WithIsSecret(true) so the SDK treats them as secrets.
Run 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:
Use TRAIT_USER for people, TRAIT_GROUP for collections, and TRAIT_ROLE for permission bundles. See Core concepts for the full list.
If a resource type declares a trait, every resource of that type must carry the matching trait. Build user, group, and role resources with NewUserResource, NewGroupResource, and NewRoleResource. A resource without its trait makes the sync fail with a “resource was missing expected trait” error.

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:
An empty NextPageToken means you’re done. The SDK calls List again until you return an empty token.

The RawId annotation

Add a RawId 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:
The principal’s resource type must match the 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.
Choose based on how access decisions are made. If “can this person administer the database?” is a real question, make admin a separate entitlement.

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:
Without the 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:
The command builds your connector, so it needs valid configuration. Pass the required flags or environment variables, or register a default capabilities builder with 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.
Build the connector, run it, and inspect the result with the baton CLI:

Common mistakes

Resource type mismatches

A grant references its principal by ResourceId (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’s uhttp 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 with field.WithIsSecret(true), as in Define configuration.

Quick reference

Common traits

See Core concepts for the complete list.

SDK helpers

V1 syncer differences

The V1 ResourceSyncer 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:
Everything else in this guide applies to both versions. V2 also gives each call a session store through SyncOpAttrs.Session, but only when the connector enables it with connectorrunner.WithSessionStoreEnabled().