Tier 1 auth setup template

Repeatable template for documenting Tier 1 vendor authentication setup. Use this template when onboarding a new Tier 1 connector to capture auth modes, scopes, credential lifecycle, and validation steps.

Use this template when onboarding a new Tier 1 vendor connector. Copy the sections below into a new document, fill in the details, and link the completed doc from the connector’s setup page. The template is designed to work for both simple API-key vendors and complex OAuth/JWT/domain-wide delegation vendors.

Vendor overview

Field	Value
Vendor / service name	e.g., Okta, Google Workspace, Datadog
Vendor documentation URL	Link to the vendor’s API authentication docs
C1 connector repo	baton-<name>
Connector type	Cloud-hosted / Self-hosted / Both

Supported API auth modes

List every authentication method the vendor API supports, then indicate which ones C1 supports today.

Auth mode	Vendor supports	C1 supports today	Notes
API key / token	Yes / No	Yes / No	e.g., “Long-lived, scoped to creating user”
OAuth 2.0 client credentials	Yes / No	Yes / No	e.g., “Short-lived tokens, auto-refresh”
OAuth 2.0 + private key (JWT)	Yes / No	Yes / No	e.g., “OIDC app with client credentials flow”
Service account JSON key (DWD)	Yes / No	Yes / No	e.g., “Google-style domain-wide delegation”
IAM role / cross-account trust	Yes / No	Yes / No	e.g., “AWS STS AssumeRole with external ID”
LDAP bind	Yes / No	Yes / No	e.g., “Simple bind or Kerberos/GSSAPI”
SCIM bearer token	Yes / No	Yes / No
Other: ________________	Yes / No	Yes / No

Recommended setup path

Describe the recommended auth method and why it is preferred. If there are multiple valid approaches, rank them.

Primary recommendation

Example: “Use OAuth 2.0 with private key (JWT) for production environments. This provides scoped access with short-lived tokens and easier credential rotation compared to long-lived API tokens.”

Auth method: e.g., OAuth 2.0 Private Key

Why this method:

• e.g., Least-privilege scopes available
• e.g., Short-lived tokens reduce blast radius
• e.g., No human-tied credentials

Alternative method (if applicable)

Example: “Use an API token for quick setup or non-production environments. Simpler to configure but uses long-lived credentials tied to an admin account.”

Auth method: e.g., API Token

When to use instead: e.g., Quick proof-of-concept, vendor doesn’t support OAuth for all required scopes

Required scopes and permissions

For sync only (read access)

List the minimum scopes or permissions required for C1 to sync data from the vendor.

Scope / permission	Purpose
e.g., okta.users.read	Read and sync user accounts
e.g., okta.groups.read	Read and sync groups and memberships
e.g., okta.apps.read	Read and sync application assignments
e.g., okta.roles.read	Read and sync admin role assignments

For sync + provisioning (read/write access)

List additional scopes or permissions required for C1 to provision and deprovision access.

Scope / permission	Purpose
e.g., okta.users.manage	Provision and deprovision user accounts
e.g., okta.groups.manage	Add and remove users from groups

Vendor admin role requirements

C1 capability	Minimum vendor role required
Sync-only	e.g., Read-Only Administrator
Sync + provision	e.g., Super Administrator or App Admin + Group Admin

Credential setup instructions

Step-by-step instructions for creating the credentials. Adapt the structure based on auth complexity.

Simple auth (API key / token)

1. Log into the vendor admin console.

2. Navigate to Settings > API > Tokens (adjust path for vendor).

3. Create a new token named ConductorOne with the scopes listed above.

4. Copy and securely store the token. You will need it when configuring the connector in C1.

Complex auth (OAuth / JWT / DWD)

Use this section for vendors that require multiple steps such as creating an application, generating keys, configuring delegation, or setting up trust relationships.

1. Create an application / service account

   Navigate to the vendor’s developer console and create a new application or service account for the C1 integration.

2. Configure authentication method

   Select the appropriate auth method (e.g., public key / private key) and generate or upload credentials.

3. Grant scopes / permissions

   Assign the required scopes from the tables above. Use the sync-only set for read-only access, or the sync + provisioning set for full access.

4. Configure delegation (if applicable)

   For domain-wide delegation or cross-account trust, configure the trust relationship between the service account and the vendor’s admin domain.

   Example for Google: Add the service account’s Client ID to Admin Console > Security > API Controls > Domain-wide Delegation with the required OAuth scopes.

   Example for AWS: Create an IAM role with a trust policy referencing C1’s service account ARN and the provided External ID.

5. Collect required values

   Record the following values — you will need them when configuring the connector in C1:

   Value	Where to find it
   e.g., Client ID	Application settings page
   e.g., Private Key (PEM)	Downloaded during key creation
   e.g., Key ID	Shown after key is added
   e.g., Customer / Tenant ID	Admin console > Account Settings
   e.g., Domain	Admin console > Domains

Rotation and expiration behavior

Field	Value
Credential type	e.g., API token, OAuth client secret, service account JSON key, IAM role
Expires automatically?	Yes (after N days) / No (manual rotation required)
Vendor-enforced max lifetime	e.g., 90 days, 1 year, unlimited
Rotation method	e.g., Generate new token in admin console and update connector settings in C1
Does rotation cause downtime?	e.g., No — old token remains valid until explicitly revoked
C1 rotation procedure	e.g., Navigate to Integrations > Connectors > [Connector] > Settings > Edit, paste new token, click Save

Rotation checklist

• Generate new credentials in the vendor’s admin console
• Update the connector configuration in C1 with the new credentials
• Verify a successful sync completes after the update
• Revoke the old credentials in the vendor’s admin console (if not auto-expired)

Known caveats

Document any known issues, limitations, or non-obvious behaviors. Assign an owner to each caveat.

Caveat	Impact	Owner
e.g., API token inherits permissions of the creating user — if that user’s role changes, the token’s effective permissions change too	Sync or provisioning may silently lose capabilities	@team-connectors
e.g., OAuth scopes must be re-granted after adding new ones — removing and re-adding the app resets all scopes	Provisioning stops working until scopes are re-granted	@team-connectors
e.g., Rate limit is 100 req/min per token; large orgs may hit this during initial sync	Sync may take longer; SDK handles retries automatically	@team-connectors

Validation

Use these commands or steps to verify that credentials are working correctly.

CLI validation

# Replace with the actual baton connector name and required flags
baton-<connector-name> \
  --<auth-flag> "<credential-value>" \
  --<domain-flag> "<domain-value>"

A successful run produces a sync.c1z file in the current directory. Inspect it with:

baton resources -f sync.c1z

Conformance validation

# Run the connector's built-in conformance checks (if available)
baton-<connector-name> \
  --<auth-flag> "<credential-value>" \
  --<domain-flag> "<domain-value>" \
  capabilities

Cloud-hosted validation

After configuring the connector in C1:

1. Navigate to Integrations > Connectors
2. Find the connector and check that its status shows Connected
3. Click the connector name and verify Last sync is recent with no errors
4. Navigate to the app’s Accounts and Entitlements tabs to confirm data was synced