Skip to main content

Documentation Index

Fetch the complete documentation index at: https://conductorone-docs-ad-account-provisioning-setup.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

This reference documents the public APIs in baton-sdk that connector developers use. The SDK follows an inversion-of-control pattern: you implement interfaces, the SDK calls your methods.

​
Connector builder interfaces

​
Connectorbuilder (entry point)

The main interface your connector must implement: 
type ConnectorBuilder interface {
    MetadataProvider
    ValidateProvider
    ResourceSyncers(ctx context.Context) []ResourceSyncer
}

// V2 preferred - uses enhanced sync options
type ConnectorBuilderV2 interface {
    MetadataProvider
    ValidateProvider
    ResourceSyncers(ctx context.Context) []ResourceSyncerV2
}
Required sub-interfaces: 
type MetadataProvider interface {
    Metadata(ctx context.Context) (*v2.ConnectorMetadata, error)
}

type ValidateProvider interface {
    Validate(ctx context.Context) (annotations.Annotations, error)
}
Usage: 
func NewConnector(ctx context.Context, in interface{}, opts ...Opt) (types.ConnectorServer, error)

// Options
func WithTicketingEnabled() Opt
func WithMetricsHandler(h metrics.Handler) Opt
func WithSessionStore(ss sessions.SessionStore) Opt

​
ResourceSyncer (core sync)

The primary interface for syncing data: 
// V1 Interface (legacy)
type ResourceSyncer interface {
    ResourceType(ctx context.Context) *v2.ResourceType
    List(ctx context.Context, parentResourceID *v2.ResourceId,
         pToken *pagination.Token) ([]*v2.Resource, string, annotations.Annotations, error)
    Entitlements(ctx context.Context, resource *v2.Resource,
                 pToken *pagination.Token) ([]*v2.Entitlement, string, annotations.Annotations, error)
    Grants(ctx context.Context, resource *v2.Resource,
           pToken *pagination.Token) ([]*v2.Grant, string, annotations.Annotations, error)
}

// V2 Interface (preferred)
type ResourceSyncerV2 interface {
    ResourceType(ctx context.Context) *v2.ResourceType
    List(ctx context.Context, parentResourceID *v2.ResourceId,
         opts resource.SyncOpAttrs) ([]*v2.Resource, *resource.SyncOpResults, error)
    Entitlements(ctx context.Context, resource *v2.Resource,
                 opts resource.SyncOpAttrs) ([]*v2.Entitlement, *resource.SyncOpResults, error)
    Grants(ctx context.Context, resource *v2.Resource,
           opts resource.SyncOpAttrs) ([]*v2.Grant, *resource.SyncOpResults, error)
}
V2 Sync Types: 
type SyncOpAttrs struct {
    SyncID    string
    PageToken string
    Session   sessions.SessionStore
}

type SyncOpResults struct {
    NextPageToken string
    Annotations   annotations.Annotations
}
Key differences V1 vs V2:
  • V2 receives SyncOpAttrs with session store for caching
  • V2 returns structured SyncOpResults instead of raw values
  • V2 is preferred for new connectors

​
ResourceTargetedSyncer (single resource fetch)

Extension for fetching a single resource by ID: 
type ResourceTargetedSyncer interface {
    ResourceSyncer
    Get(ctx context.Context, resourceId *v2.ResourceId,
        parentResourceId *v2.ResourceId) (*v2.Resource, annotations.Annotations, error)
}
Enables CAPABILITY_TARGETED_SYNC for faster incremental updates.

​
ResourceProvisioner (grant/revoke)

For connectors that can modify access: 
// V1 (legacy)
type ResourceProvisioner interface {
    ResourceSyncer
    Grant(ctx context.Context, resource *v2.Resource,
          entitlement *v2.Entitlement) (annotations.Annotations, error)
    Revoke(ctx context.Context, grant *v2.Grant) (annotations.Annotations, error)
}

// V2 (preferred) - Grant returns created grants
type ResourceProvisionerV2 interface {
    ResourceSyncer
    Grant(ctx context.Context, resource *v2.Resource,
          entitlement *v2.Entitlement) ([]*v2.Grant, annotations.Annotations, error)
    Revoke(ctx context.Context, grant *v2.Grant) (annotations.Annotations, error)
}
V2 advantage: Grant() returns list of created grants, useful when one grant creates multiple assignments. Enables CAPABILITY_PROVISION.

​
AccountManager (user provisioning)

For creating user accounts (JIT provisioning): 
type AccountManager interface {
    ResourceSyncer
    CreateAccount(ctx context.Context,
        accountInfo *v2.AccountInfo,
        credentialOptions *v2.LocalCredentialOptions,
    ) (CreateAccountResponse, []*v2.PlaintextData, annotations.Annotations, error)

    CreateAccountCapabilityDetails(ctx context.Context,
    ) (*v2.CredentialDetailsAccountProvisioning, annotations.Annotations, error)
}

type CreateAccountResponse interface {
    proto.Message
    GetIsCreateAccountResult() bool
}
Response types:
  • *v2.CreateAccountResponse_SuccessResult - Account created successfully
  • *v2.CreateAccountResponse_ActionRequiredResult - User action needed
Enables CAPABILITY_ACCOUNT_PROVISIONING.

​
ResourceManager (create/delete resources)

For creating and deleting resources: 
// V1 (legacy)
type ResourceManager interface {
    ResourceSyncer
    Create(ctx context.Context, resource *v2.Resource) (*v2.Resource, annotations.Annotations, error)
    Delete(ctx context.Context, resourceId *v2.ResourceId) (annotations.Annotations, error)
}

// V2 (preferred) - Delete receives parent ID
type ResourceManagerV2 interface {
    ResourceSyncer
    Create(ctx context.Context, resource *v2.Resource) (*v2.Resource, annotations.Annotations, error)
    Delete(ctx context.Context, resourceId *v2.ResourceId,
           parentResourceID *v2.ResourceId) (annotations.Annotations, error)
}

// Separate interfaces if you only need one operation
type ResourceDeleter interface {
    ResourceSyncer
    Delete(ctx context.Context, resourceId *v2.ResourceId) (annotations.Annotations, error)
}

type ResourceDeleterV2 interface {
    ResourceSyncer
    Delete(ctx context.Context, resourceId *v2.ResourceId,
           parentResourceID *v2.ResourceId) (annotations.Annotations, error)
}
Enables CAPABILITY_RESOURCE_CREATE and CAPABILITY_RESOURCE_DELETE.

​
CredentialManager (credential rotation)

For rotating credentials: 
type CredentialManager interface {
    ResourceSyncer
    Rotate(ctx context.Context,
        resourceId *v2.ResourceId,
        credentialOptions *v2.LocalCredentialOptions,
    ) ([]*v2.PlaintextData, annotations.Annotations, error)

    RotateCapabilityDetails(ctx context.Context,
    ) (*v2.CredentialDetailsCredentialRotation, annotations.Annotations, error)
}
Returns plaintext credentials; the SDK encrypts them before sending to C1. Enables CAPABILITY_CREDENTIAL_ROTATION.

​
CustomActionManager (custom actions)

For connectors with custom operations: 
type CustomActionManager interface {
    ListActionSchemas(ctx context.Context) ([]*v2.BatonActionSchema, annotations.Annotations, error)
    GetActionSchema(ctx context.Context, name string) (*v2.BatonActionSchema, annotations.Annotations, error)
    InvokeAction(ctx context.Context, name string, args *structpb.Struct,
    ) (string, v2.BatonActionStatus, *structpb.Struct, annotations.Annotations, error)
    GetActionStatus(ctx context.Context, id string,
    ) (v2.BatonActionStatus, string, *structpb.Struct, annotations.Annotations, error)
}
Enables CAPABILITY_ACTIONS.

​
EventFeed (real-time events)

For streaming events from the target system: 
// V2 (preferred) - Multiple feeds
type EventProviderV2 interface {
    ConnectorBuilder
    EventFeeds(ctx context.Context) []EventFeed
}

type EventFeed interface {
    ListEvents(ctx context.Context, earliestEvent *timestamppb.Timestamp,
               pToken *pagination.StreamToken,
    ) ([]*v2.Event, *pagination.StreamState, annotations.Annotations, error)
    EventFeedMetadata(ctx context.Context) *v2.EventFeedMetadata
}
Enables CAPABILITY_EVENT_FEED_V2.

​
Type builders

​
Resource builder

// Create resource type definition
func NewResourceType(name string, requiredTraits []v2.ResourceType_Trait,
                     msgs ...proto.Message) *v2.ResourceType

// Create resource ID
func NewResourceID(resourceType *v2.ResourceType, objectID interface{}) (*v2.ResourceId, error)

// Create resource instance
func NewResource(name string, resourceType *v2.ResourceType,
                 objectID interface{}, resourceOptions ...ResourceOption) (*v2.Resource, error)
Resource Options: 
func WithAnnotation(msgs ...proto.Message) ResourceOption
func WithExternalID(externalID *v2.ExternalId) ResourceOption
func WithParentResourceID(parentResourceID *v2.ResourceId) ResourceOption
func WithDescription(description string) ResourceOption
func WithUserTrait(opts ...UserTraitOption) ResourceOption
func WithGroupTrait(opts ...GroupTraitOption) ResourceOption
func WithRoleTrait(opts ...RoleTraitOption) ResourceOption
func WithAppTrait(opts ...AppTraitOption) ResourceOption
func WithSecretTrait(opts ...SecretTraitOption) ResourceOption

​
User trait options

func WithStatus(status v2.UserTrait_Status_Status) UserTraitOption
func WithDetailedStatus(status v2.UserTrait_Status_Status, details string) UserTraitOption
func WithEmail(email string, primary bool) UserTraitOption
func WithUserLogin(login string, aliases ...string) UserTraitOption
func WithEmployeeID(employeeIDs ...string) UserTraitOption
func WithUserIcon(assetRef *v2.AssetRef) UserTraitOption
func WithUserProfile(profile map[string]interface{}) UserTraitOption
func WithAccountType(accountType v2.UserTrait_AccountType) UserTraitOption
func WithCreatedAt(createdAt time.Time) UserTraitOption
Status values:
StatusMeaning
STATUS_ENABLEDActive user
STATUS_DISABLEDSuspended user
STATUS_DELETEDSoft-deleted user
STATUS_UNSPECIFIEDUnknown status
Account types:
TypeMeaning
ACCOUNT_TYPE_HUMANHuman user
ACCOUNT_TYPE_SERVICEService account
ACCOUNT_TYPE_SYSTEMSystem account

​
Entitlement builder

// Permission entitlement (e.g., "admin", "editor")
func NewPermissionEntitlement(resource *v2.Resource, name string,
                              entitlementOptions ...EntitlementOption) *v2.Entitlement

// Assignment entitlement (e.g., group membership)
func NewAssignmentEntitlement(resource *v2.Resource, name string,
                              entitlementOptions ...EntitlementOption) *v2.Entitlement

// Generic entitlement
func NewEntitlement(resource *v2.Resource, name, purposeStr string,
                    entitlementOptions ...EntitlementOption) *v2.Entitlement

// Generate entitlement ID
func NewEntitlementID(resource *v2.Resource, permission string) string
Entitlement Options: 
func WithAnnotation(msgs ...proto.Message) EntitlementOption
func WithGrantableTo(grantableTo ...*v2.ResourceType) EntitlementOption
func WithDisplayName(displayName string) EntitlementOption
func WithDescription(description string) EntitlementOption

​
Grant builder

// Create grant linking principal to entitlement
func NewGrant(resource *v2.Resource, entitlementName string,
              principal GrantPrincipal, grantOptions ...GrantOption) *v2.Grant

// Generate grant ID
func NewGrantID(principal GrantPrincipal, entitlement *v2.Entitlement) string
Grant Options: 
func WithGrantMetadata(metadata map[string]interface{}) GrantOption
func WithExternalPrincipalID(externalID *v2.ExternalId) GrantOption
func WithAnnotation(msgs ...proto.Message) GrantOption

​
Pagination

​
Token types

type Token struct {
    Size  int    // Page size
    Token string // Opaque token from API
}

type StreamToken struct {
    Size   int    // Page size
    Cursor string // Stream cursor
}

type StreamState struct {
    Cursor  string // Next cursor
    HasMore bool   // More events available
}

​
Pagination bag

For nested or multi-resource pagination: 
type Bag struct {
    // Internal state stack
}

func (pb *Bag) Push(state PageState)
func (pb *Bag) Pop() *PageState
func (pb *Bag) Next(pageToken string) error
func (pb *Bag) NextToken(pageToken string) (string, error)
func (pb *Bag) Current() *PageState
func (pb *Bag) Marshal() (string, error)
func (pb *Bag) Unmarshal(data string) error

​
HTTP client utilities

​
Creating clients

func NewClient(ctx context.Context, options ...Option) (*http.Client, error)

// Options
func WithTLSClientConfig(tlsConfig *tls.Config) Option
func WithLogger(log bool, logger *zap.Logger) Option
func WithUserAgent(userAgent string) Option

​
Caching

func CreateCacheKey(req *http.Request) (string, error)
func ClearCaches(ctx context.Context) error
Features: built-in response caching, rate limit extraction, automatic retry with exponential backoff on 429.

​
Session store

For caching data across pagination calls: 
type SessionStore interface {
    Get(ctx context.Context, key string) (interface{}, error)
    Set(ctx context.Context, key string, value interface{}) error
    Clear(ctx context.Context, filters ...SessionFilter) error
    Stats(ctx context.Context) StoreStats
}
Accessing in sync methods (V2): 
func (u *userBuilder) List(ctx context.Context, parentID *v2.ResourceId,
    opts resource.SyncOpAttrs) ([]*v2.Resource, *resource.SyncOpResults, error) {

    // Use session store for caching
    if cached, err := opts.Session.Get(ctx, "user_cache"); err == nil {
        // Use cached data
    }

    // Store for next call
    opts.Session.Set(ctx, "user_cache", userData)
}

​
Capabilities matrix

Capabilities are automatically detected based on which interfaces you implement:
CapabilityInterface required
CAPABILITY_SYNCResourceSyncer
CAPABILITY_TARGETED_SYNCResourceTargetedSyncer
CAPABILITY_PROVISIONResourceProvisioner or ResourceProvisionerV2
CAPABILITY_ACCOUNT_PROVISIONINGAccountManager
CAPABILITY_RESOURCE_CREATEResourceManager
CAPABILITY_RESOURCE_DELETEResourceManager, ResourceDeleter, or ResourceDeleterV2
CAPABILITY_CREDENTIAL_ROTATIONCredentialManager
CAPABILITY_EVENT_FEED_V2EventFeed
CAPABILITY_TICKETINGTicketManager (with WithTicketingEnabled option)
CAPABILITY_ACTIONSCustomActionManager

​
Quick reference

​
Import paths

import (
    "github.com/conductorone/baton-sdk/pkg/connectorbuilder"
    "github.com/conductorone/baton-sdk/pkg/pagination"
    "github.com/conductorone/baton-sdk/pkg/types/entitlement"
    "github.com/conductorone/baton-sdk/pkg/types/grant"
    "github.com/conductorone/baton-sdk/pkg/types/resource"
    "github.com/conductorone/baton-sdk/pkg/uhttp"
    "github.com/conductorone/baton-sdk/pb/c1/connector/v2"
)

​
Common patterns

TaskFunctions
Create resource typeresource.NewResourceType(name, traits)
Create resourceresource.NewResource(name, type, id, opts...)
Add user traitresource.WithUserTrait(resource.WithEmail(...))
Create entitlemententitlement.NewAssignmentEntitlement(resource, name)
Create grantgrant.NewGrant(resource, entitlement, principal)
Handle paginationpagination.Bag{} with Marshal/Unmarshal