What’s a service principal?
A service principal is a dedicated, non-human identity purpose-built for automation. It appears in the user directory alongside human users, but it’s designed for scripts, CI/CD pipelines, Terraform runs, and API integrations. Each service principal:- Has a display name and unique ID
- Can be assigned ConductorOne roles, just like a human user
- Has owners who manage it
- Can have multiple credentials or federation trusts
Two ways to authenticate
Service principals support two authentication methods. You can use either one, or both on the same service principal.| Client credentials | Workload federation | |
|---|---|---|
| How | Client ID + secret sent to token endpoint | External OIDC (OpenID Connect) token exchanged for ConductorOne token |
| Secrets | Client secret must be stored and rotated | No secrets — uses your CI/CD platform’s built-in OIDC |
| Best for | Local development, scripts, cron jobs, Terraform (simple setup) | GitHub Actions, GitLab CI, HCP Terraform, AWS (production) |
| Credential lifetime | Maximum 180 days; must be rotated before expiry | No credentials to manage; tokens are per-run |
| Security | Secret can leak; mitigate with IP restrictions + expiration + scoped roles | No secret to leak; token valid only for a single CI/CD run |
| Grant type | client_credentials | urn:ietf:params:oauth:grant-type:token-exchange |
Choosing the right method
- Use client credentials if you want a straightforward path to calling the API. Best for scripts, local development, and environments where storing a secret is acceptable.
- Use workload federation for production CI/CD. No secrets to rotate, tighter scoping, and tokens are tied to individual workflow runs.
Environment variables
All ConductorOne client tools (Go SDK, Terraform provider, Cone CLI, oidc-token-action) recognize the same environment variables:| Variable | Purpose |
|---|---|
CONDUCTORONE_CLIENT_ID | Client ID for authentication (client credentials or workload federation trust) |
CONDUCTORONE_CLIENT_SECRET | Ed25519 private key for client credentials |
CONDUCTORONE_ACCESS_TOKEN | Pre-exchanged bearer token (highest priority, skips all other auth) |
CONDUCTORONE_OIDC_TOKEN | Raw OIDC JWT for workload federation token exchange |
CONDUCTORONE_TENANT_DOMAIN | Tenant domain override |
CONDUCTORONE_SERVER_URL | Full server URL override |
CONDUCTORONE_ACCESS_TOKEN— static bearer token, no exchange neededCONDUCTORONE_OIDC_TOKEN— token exchange usingCONDUCTORONE_CLIENT_IDCONDUCTORONE_CLIENT_ID+CONDUCTORONE_CLIENT_SECRET— Ed25519 JWT assertion
Before you begin
Before creating service principals:- Contact your ConductorOne account team to enable the feature (it’s gated behind a feature flag during early access)
- You need Super Admin permissions to create and manage service principals
Next steps
Quick start: Client credentials
Get from zero to a working API call in under 5 minutes.
Workload federation
Set up secretless authentication from CI/CD platforms.
Service principal limits
| Limit | Value |
|---|---|
| Maximum credential lifetime | 180 days (rotation required) |
| CEL expression size | 1,024 bytes |
| IP address ranges per credential or trust | 32 |
| Workload federation provider requirement | Publicly accessible JWKS (JSON Web Key Set) endpoint |
Credential expiration can’t be extended after creation. To continue access, create a new credential with the desired expiration and revoke the old one. See credential rotation.