Provisioning is optional, and many connectors only sync. It’s what moves your connector from showing access to managing it.
This page covers provisioning in connectors you build with the Baton SDK. The configuration-driven connectors (HTTP, SQL, and SCIM authoring) can provision through configuration, and C1AI custom connectors sync access data only. See Choose how to connect an application to compare the options.
Enable provisioning at runtime
Implementing the provisioning interfaces makes your connector advertise the matching capabilities. To make the operations runnable in daemon mode, start the connector with the--provisioning flag, or set BATON_PROVISIONING=true. Without it, grant, revoke, create, delete, and rotate requests fail with a FailedPrecondition error that says provisioning isn’t enabled.
Custom actions don’t need the flag. The SDK serves actions whether or not provisioning is enabled.
The provisioning interfaces
This page uses the V2 syncer interfaces from Building connectors. Your resource builders implement the interfaces below in addition toResourceSyncerV2. The SDK detects which operations a builder supports from the methods it implements.
Grant and revoke
In
Grant, the SDK passes the principal, the resource that receives access, as the first resource argument. The resource that offers the entitlement is entitlement.Resource. The examples on this page name the argument principal.Grant returns a list of grants, which handles cases where one logical grant creates several underlying grants. The older GrantProvisioner interface returns no grants and still works. Use GrantProvisionerV2 for new connectors.
CreateAccount
DeleteResource and CreateResource
ResourceManagerV2 provides both creation and deletion.
Implement grant and revoke
When to implement
If your target system can add and remove users from groups, roles, or permissions through its API, implementGrant and Revoke. That covers most access control systems.
Grant
sdkGrant is github.com/conductorone/baton-sdk/pkg/types/grant, and isAlreadyExistsError stands in for your own check. entitlement.Slug matches the name you gave the entitlement when you built it with the SDK’s entitlement helpers.
Revoke
Idempotency and errors
CallingGrant twice for the same user and entitlement should succeed both times. This matters more because the SDK retries Grant and Revoke automatically (see below).
- Grant: If the user already holds the entitlement, return success. An HTTP 409 Conflict usually means “already exists.”
- Revoke: If the user doesn’t hold the entitlement, return success. An HTTP 404 Not Found usually means “already revoked.”
GrantAlreadyExists and GrantAlreadyRevoked annotations for these cases. They describe what happened: the grant wasn’t created because it already existed, or it wasn’t revoked because it didn’t exist. Return one with a nil error, as in the examples above.
Error semantics
The SDK retriesGrant and Revoke, but only when the error carries a gRPC Unavailable or DeadlineExceeded status. It makes up to three attempts, starting with a 15-second delay and capping at 60 seconds. Any other error fails the operation immediately, and an error from a plain fmt.Errorf has no status code, so it isn’t retried.
Return the status that matches the failure:
CreateAccount, Delete, and credential rotation have no automatic retry. Credential issuance deliberately avoids it.
Edge cases
Validate the principal type
Always check that the principal is the expected type:Store grant IDs
If the target system returns an assignment ID, you can use it as the grant ID:Grants sync method produces for the same assignment. Grant IDs are an external contract, so use the same scheme in both places.
Multiple entitlement types
If a resource offers several entitlements, dispatch on the slug:CreateAccount
CreateAccount provisions a user account in the target system when C1 needs it, so the account doesn’t have to exist beforehand.
When to implement
- The target system can create user accounts through its API.
- You want to support just-in-time provisioning workflows.
- Account creation doesn’t require an interactive sign-up.
Declare the credential options
CreateAccountCapabilityDetails tells C1 which credential options your connector supports and which one it prefers. The preferred option is required, and it must appear in the supported list. Without a valid preferred option, the connector fails when C1 asks for its capabilities.
NO_PASSWORD, SSO, ENCRYPTED_PASSWORD, API_KEY, KEYPAIR, TOKEN, and CLIENT_SECRET.
Create the account
crypto is github.com/conductorone/baton-sdk/pkg/crypto. GeneratePassword returns a random password for the RandomPassword option or the supplied value for PlaintextPassword, and returns an error for options that carry no password.
AccountInfo.Profile is a structpb.Struct, so read profile attributes from its Fields map. AccountInfo also has Login and LoginAliases.
Result types
The first return value is one of four result types:Routing
C1 selects the resource type for account creation with the request’s resource type ID. If the request leaves it empty, the SDK uses the connector’s only account manager, or the one registered on theuser resource type when there are several. Register your account manager on the user resource type so default routing works.
If your connector still implements the older form that takes *v2.CredentialOptions, migrate it to *v2.LocalCredentialOptions. The SDK rejects the older form at startup.
DeleteResource
DeleteResource removes a resource, such as a user or group, from the target system.
When to implement
- You want to deprovision users when they leave.
- The target system can delete resources through its API.
- You want cleanup automation.
Basic pattern
CreateResource
Create creates a resource, such as a group, in the target system and returns the resource as the target system now knows it:
ResourceManagerV2Limited interface, which pairs Create with Delete, so implement both.
Rotate credentials
A builder that implementsRotate and RotateCapabilityDetails lets C1 replace the credential on an account, such as a service account’s password. Rotate returns the new credential as plaintext data.
RotateCapabilityDetails declares supported and preferred credential options, the same way CreateAccountCapabilityDetails does.
For connectors that mint new credentials for an existing identity, such as an API key or token, the SDK also provides CredentialIssuerV2 with Issue and IssueCapabilityDetails methods. The secret resource type that Issue returns must have a ResourceDeleterV2, so every issued credential can be revoked.
Custom actions
Custom actions let C1 run operations that aren’t grants, revokes, or account changes, such as disabling a user or updating a profile. You describe each action with a schema and register a handler for it. To register actions that aren’t tied to a resource, implementGlobalActionProvider on your connector:
config is github.com/conductorone/baton-sdk/pb/c1/config/v1, and actions is github.com/conductorone/baton-sdk/pkg/actions. The actions package also has helpers to read arguments (GetStringArg, GetIntArg, GetBoolArg, GetResourceIDArg, and the Require variants) and to build return values (NewReturnValues with NewStringReturnField and similar).
To register actions for one resource type, implement ResourceActionProvider on that resource’s builder. Its ResourceActions(ctx, registry) method registers actions the same way.
The ActionType values tell C1 which standard operation an action performs, such as ACTION_TYPE_ACCOUNT_DISABLE or ACTION_TYPE_ACCOUNT_ENABLE. Omit it for actions that don’t match a standard operation.
Older connectors register actions with
RegisterActionManager or CustomActionManager. The SDK marks both deprecated. Use GlobalActionProvider and ResourceActionProvider in new connectors.Declare capabilities
The SDK generates your capabilities from the interfaces your builders implement. You don’t write them by hand. Generate the capability manifest from the connector binary:Interface-to-capability mapping
Test provisioning locally
You can run provisioning operations from the command line, without C1. First sync the connector to a.c1z file, then run an operation against it. These flags are hidden from --help:
{resource type}:{resource ID}:{slug}, and a grant ID has the form {entitlement ID}:{principal type}:{principal ID}. The command-line operations switch provisioning on for you. The same pattern works for --create-account-login, --delete-resource with --delete-resource-type, --rotate-credentials with --rotate-credentials-type, and --invoke-action with --invoke-action-args.