> ## Documentation Index
> Fetch the complete documentation index at: https://conductorone-docs-ia-reframe-draft.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Service principals

> Create machine identities for API automation with client credentials or secretless workload federation.

Service principals are machine identities in C1. They give your scripts, CI/CD pipelines, and Terraform runs their own identity and credentials, separate from any human user.

## 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 C1 roles, just like a human user
* Has owners who manage it
* Can have multiple credentials or federation trusts

<Tip>
  You don't need a service principal to use the C1 API for personal use. You can use existing personal API credentials (**Profile** > **AI & API** > **API credentials**) for individual tasks. Service principals are designed for shared automation where the identity should not be tied to a specific person.
</Tip>

## 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 it works**        | Client ID + secret sent to token endpoint                                  | External OIDC (OpenID Connect) token exchanged for C1 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 C1 client tools (Go SDK, [Terraform provider](/developer/terraform), [Cone CLI](/product/cli/install), 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                                                       |

When multiple variables are set, tools use this priority order:

1. `CONDUCTORONE_ACCESS_TOKEN` -- static bearer token, no exchange needed
2. `CONDUCTORONE_OIDC_TOKEN` -- token exchange using `CONDUCTORONE_CLIENT_ID`
3. `CONDUCTORONE_CLIENT_ID` + `CONDUCTORONE_CLIENT_SECRET` -- Ed25519 JWT assertion

## Before you begin

Before creating service principals:

1. Contact your C1 account team to enable the feature.
2. You need **[Super Admin](/product/admin/user-roles#super-administrator)** permissions to create and manage service principals.

## Next steps

<Columns cols={2}>
  <Card title="Quick start: Client credentials" icon="key" href="/product/admin/service-principals/client-credentials">
    Get from zero to a working API call in under 5 minutes.
  </Card>

  <Card title="Workload federation" icon="shield-check" href="/product/admin/service-principals/workload-federation">
    Set up secretless authentication from CI/CD platforms.
  </Card>
</Columns>

## Service principal limits

| Limit                                             | Value                                                |
| :------------------------------------------------ | :--------------------------------------------------- |
| Maximum credential lifetime                       | 180 days (rotation required)                         |
| [CEL expression](/product/admin/expressions) size | 1,024 bytes                                          |
| IP address ranges per credential or trust         | 32                                                   |
| Workload federation provider requirement          | Publicly accessible JWKS (JSON Web Key Set) endpoint |

<Note>
  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](/product/admin/service-principals/manage#credential-rotation).
</Note>