Skip to main content
Sync tells C1 what access exists. Provisioning lets C1 change access. 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 to ResourceSyncerV2. 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.
The V2 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

A builder that implements ResourceManagerV2 provides both creation and deletion.

Implement grant and revoke

Know your entities. In Grant and Revoke, data comes from two sources:
  • Principal: who is getting access. It provides context such as the workspace, org, or tenant.
  • Entitlement: what access they’re getting. It provides the role or permission ID.
When you extract IDs, verify that each one comes from the right entity.

When to implement

If your target system can add and remove users from groups, roles, or permissions through its API, implement Grant 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

Make operations idempotent. When a grant already exists or a revoke target isn’t found, return success. The desired state is achieved.
Calling Grant 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.”
The SDK defines the 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 retries Grant 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:
Revoke then receives the grant with that ID, so you can delete the exact assignment instead of searching for it. The ID you set here must match the ID that your 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.
The other options are 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 the user 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:
The SDK recognizes a resource manager by the ResourceManagerV2Limited interface, which pairs Create with Delete, so implement both.

Rotate credentials

A builder that implements Rotate 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, implement GlobalActionProvider 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:
The command builds your connector, so it needs valid configuration. The output lists each resource type’s capabilities:

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:
An entitlement ID has the form {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.

Quick reference

Interfaces

Method signatures

Idempotency checklist