baton-sdk that connector developers use. The SDK follows an inversion-of-control pattern: you implement interfaces, and the SDK calls your methods. For guided walkthroughs, see Building connectors and Implementing provisioning.
Connector builder interfaces
The connector
Your connector type implementsConnectorBuilderV2. It declares the connector’s metadata, validates its configuration, and returns one resource syncer per resource type:
ConnectorBuilder is the older form. It’s the same interface, but ResourceSyncers returns []ResourceSyncer.
If your connector has a Close() error or Close(ctx context.Context) error method, the SDK calls it at shutdown.
Don’t set capabilities in Metadata. The SDK computes them from the interfaces that your syncers implement. See Capabilities matrix.
Wiring a connector
config.RunConnector is the standard entry point. It builds the command-line interface from your configuration schema, creates your connector, and runs it:
cf argument is a constructor that receives your generated configuration struct and returns the connector:
RunConnector wraps your connector with connectorbuilder.NewConnector itself. The []connectorbuilder.Opt you return configures that wrapper:
connectorrunner.Option values you pass to RunConnector configure the runner. Two you’re likely to need are connectorrunner.WithSessionStoreEnabled(), covered under Session store, and connectorrunner.WithDefaultCapabilitiesConnectorBuilderV2, which lets the capabilities command run without full configuration. See Configuration schema reference for how to define the schema.
Syncer interfaces
ResourceSyncerV2
ResourceSyncerV2 is the primary interface for syncing data:
- V2 receives a
SyncOpAttrswith the page token, the sync ID, and the session store. - V2 returns a
SyncOpResultsinstead of a token string and annotations.
ResourceSyncer has the same four methods. Its paged methods take a *pagination.Token and return (results, nextPageToken string, annotations.Annotations, error).
Optional syncer extensions
These interfaces add behavior to a syncer. The SDK detects them by type assertion.
A resource type that carries the
TypeScopedGrants or TypeScopedEntitlements annotation must implement the matching interface, or NewConnector fails.
Provisioning interfaces
The SDK detects provisioning support from these interfaces on your syncers. They are covered in detail in Implementing provisioning.
The full interfaces combine a syncer with these methods.
ResourceProvisionerV2 embeds ResourceSyncerV2, ResourceManagerV2 embeds ResourceSyncerV2, and AccountManagerV2 embeds ResourceSyncerV2 and AccountManagerLimited. Each also has a V1 counterpart that embeds ResourceSyncer instead.
CreateAccount returns one of four response types: CreateAccountResponse_SuccessResult, _ActionRequiredResult, _AlreadyExistsResult, or _InProgressResult.
The older CredentialOptions form of CreateAccount and Rotate is rejected at startup. Use LocalCredentialOptions.
Custom actions
Register custom actions throughGlobalActionProvider on your connector, or ResourceActionProvider on a resource builder:
CAPABILITY_ACTIONS. The actions package also has helpers to read arguments (GetStringArg, GetIntArg, GetBoolArg, GetResourceIDArg, and the Require variants) and to build return values (NewReturnValues). See Custom actions for a complete example.
CustomActionManager and RegisterActionManager are deprecated. Use the providers above.Event feeds
Connectors that stream events from the target system implementEventFeedsLimited:
CAPABILITY_EVENT_FEED_V2. A connector built on ConnectorBuilder (V1) implements EventProviderV2, which combines ConnectorBuilder with EventFeedsLimited.
Type builders
Resource builder
NewAppResource, NewSecretResource, NewScopeBindingResource, and NewManagedDeviceResource follow the same pattern.
Resource options:
WithExternalID is deprecated and no longer used. The SDK identifies a resource by its resource type and resource ID.User trait options
Account types:
This isn’t an exhaustive list of option functions. Group, role, app, secret, scope binding, and managed device traits each have their own option functions in the
resource package.
Entitlement builder
Grant builder
principal is a *v2.ResourceId or a *v2.Resource. entitlementName is the name you gave the entitlement, which becomes its slug.
Grant options:
WithExternalPrincipalID is deprecated and no longer used.
Pagination
Token types
Pagination bag
For nested or multi-list pagination:pagination.GenBag[T] is a generic version that holds a stack of your own state type. Create one with pagination.GenBagFromToken[T](token *pagination.Token).
If the API rejects a page token, return pagination.NewRestartActionError(restartPageToken, reason string) to restart the call. See Pagination patterns for usage.
HTTP client utilities
Theuhttp package builds HTTP clients that work with the SDK’s error handling. It has two layers: an *http.Client factory, and a BaseHttpClient wrapper that sends requests and decodes responses.
Create a client
uhttp.NewBearerAuth(token) and uhttp.NewBasicAuth(username, password) return credentials whose GetClient(ctx, options...) method builds the *http.Client.
Send requests
Do reads and closes the response body for you. For pagination helpers, see Pagination patterns.
Caching, errors, and retries
uhttp caches successful GET responses and can extract rate limit data from responses when you pass WithRatelimitData. It doesn’t retry requests. It translates HTTP statuses such as 429, 502, 503, and 504 into the gRPC Unavailable status, and the SDK retries calls that fail with Unavailable or DeadlineExceeded.
Session store
The session store caches data for the duration of a sync. It’s available only to V2 syncers, and only when you enable it:session.ErrSessionStoreDisabled.
The store holds byte slices:
session package wraps it with typed JSON helpers, such as session.GetJSON[T] and session.SetJSON:
session is github.com/conductorone/baton-sdk/pkg/session, and grantsFrom stands in for your own code. The store limits how much data it holds, so cache only what you need.