baton-segment

baton-segment

baton-segment is a connector for Twilio Segment built using the Baton SDK. It syncs IAM users, groups, roles, invitations, and resource access from your Segment workspace for complete access visibility.

Check out Baton to learn more about the project in general.

Prerequisites

• A Twilio Segment workspace with Team or Business tier (required for API access)
• A Personal Access Token (PAT) with appropriate permissions

Feature Availability by Plan

Note: If you attempt to use features not available in your plan, you'll receive an error like:

{
    "errors": [
        {
            "type": "bad-request",
            "message": "Your plan does not include User Groups. Contact sales to upgrade to business tier."
        }
    ]
}

Creating an Access Token

1. Log in to your Segment workspace
2. Navigate to Settings > Workspace Settings > Access Management
3. Go to the Tokens tab
4. Click Create Token and select the appropriate scopes
5. Copy the generated token

For more information, see Segment's Public API documentation.

Getting Started

brew

brew install conductorone/baton/baton conductorone/baton/baton-segment

BATON_TOKEN=your-access-token baton-segment
baton resources

docker

docker run --rm -v $(pwd):/out -e BATON_TOKEN=your-access-token ghcr.io/conductorone/baton-segment:latest -f "/out/sync.c1z"
docker run --rm -v $(pwd):/out ghcr.io/conductorone/baton:latest -f "/out/sync.c1z" resources

source

go install github.com/conductorone/baton/cmd/baton@main
go install github.com/conductorone/baton-segment/cmd/baton-segment@main

BATON_TOKEN=your-access-token baton-segment

baton resources

Data Model

baton-segment syncs the following resources from your Segment workspace:

IAM Resources

Data Resources

Entitlements

Role-based entitlements are created on scope resources (workspace, source, warehouse, function, space) using the ternary relationship model: Principal → Role → Scope Resource.

Grants

• Workspace → User: All users are members of the workspace
• Scope Resource → User/Group: Role assignments (e.g., "Workspace Owner on C1-twilio-test")
• Group → User: Group membership grants

Provisioning

baton-segment supports the following provisioning capabilities:

Group Management

Role Management

Account Management

Example: Grant Group Membership

baton-segment --token $TOKEN
baton grant --entitlement "group:group_001:member" --principal-type user --principal "user:user_123"

Example: Assign Role to User on Workspace

baton-segment --token $TOKEN
baton grant --entitlement "workspace:workspace_001:workspace-owner" --principal-type user --principal "user:user_123"

Example: Revoke Role from Group on Source

baton-segment --token $TOKEN
baton revoke --grant "source:source_001:source-admin:group:group_001"

Configuration

Development

Running the Test Server

For development without real API credentials, you can use the mock test server:

# Build the test server
go build -o dist/test-server ./cmd/test-server

# Start the test server
./dist/test-server

# In another terminal, run the connector
./dist/darwin_arm64/baton-segment \
  --base-url http://localhost:8080 \
  --token test-segment-token-12345

The test server provides mock endpoints for all Segment API operations used by the connector.

Building

make build

Contributing, Support and Issues

We started Baton because we were tired of taking screenshots and manually building spreadsheets. We welcome contributions, and ideas, no matter how small—our goal is to make identity and permissions sprawl less painful for everyone. If you have questions, problems, or ideas: Please open a GitHub Issue!

See CONTRIBUTING.md for more details.

baton-segment Command Line Usage

baton-segment

Usage:
  baton-segment [flags]
  baton-segment [command]

Available Commands:
  capabilities       Get connector capabilities
  completion         Generate the autocompletion script for the specified shell
  help               Help about any command

Flags:
      --base-url string            Base URL for the Segment API ($BATON_BASE_URL) (default "https://api.segmentapis.com")
      --client-id string           The client ID used to authenticate with ConductorOne ($BATON_CLIENT_ID)
      --client-secret string       The client secret used to authenticate with ConductorOne ($BATON_CLIENT_SECRET)
  -f, --file string                The path to the c1z file to sync with ($BATON_FILE) (default "sync.c1z")
  -h, --help                       help for baton-segment
      --log-format string          The output format for logs: json, console ($BATON_LOG_FORMAT) (default "json")
      --log-level string           The log level: debug, info, warn, error ($BATON_LOG_LEVEL) (default "info")
  -p, --provisioning               Enable provisioning support ($BATON_PROVISIONING)
      --ticketing                  Enable ticketing support ($BATON_TICKETING)
      --token string        Personal Access Token for Segment API ($BATON_TOKEN)
  -v, --version                    version for baton-segment

Use "baton-segment [command] --help" for more information about a command.