# CircleCI

Configure an OIDC identity provider for CircleCI pipelines. Exchange CIRCLE_OIDC_TOKEN for Buddy API token without storing permanent credentials.

An OIDC identity provider for CircleCI enables secure pipeline authentication to the Buddy API without storing credentials. CircleCI provides the OIDC token in the `CIRCLE_OIDC_TOKEN` variable.

## Configuration

When selecting **CircleCI** in the OIDC identity provider configuration, you will configure:

![CircleCI OIDC identity provider configuration form with fields for organization ID, issuer URL, trust conditions, and scopes](/docs/account/security/oidc-identity-provider/identity-provider-circleci.png 640x770)

- **OIDC Identity Provider Name**: A descriptive name
- **Lifetime**: Token validity time (counted from exchange moment). Available options:
  - 10 min
  - 30 min
  - 1 h
  - 1 h 30 min
  - 3 h
  - 8 h
- **Audience/CircleCI Organization ID** `Required`: CircleCI organization UUID.  
Find it in CircleCI: **Organization Settings** → **Organization ID**
- **Issuer/Provider URL**: Automatically filled after entering Organization ID (`https://oidc.circleci.com/org/<organization_id>`)
- **Trust Conditions**: Define conditions based on CircleCI claims (see [Trust Conditions](/docs/api/getting-started/identity-provider/trust-conditions.md))

<Hint type="info">
If you need the **Project ID** for trust condition, find it in CircleCI: **Project Settings** → **Overview**.
</Hint>
- **IP Access Restrictions**: Optional IP subnet masks for additional security
- **Workspace Access**: By default, access to all the user’s workspaces. Uncheck to limit to selected ones.
- **Scopes**: Select specific permissions. OIDC identity providers use the same scopes as OAuth 2.0 applications. For detailed descriptions, see [Supported scopes](/docs/api/getting-started/oauth2/introduction.md#supported-scopes)

After clicking **Add this OIDC Identity Provider** you will receive **Provider ID** and ready-to-use code in the **USE WITH CURL** section.

## Usage in CircleCI

After creating an OIDC identity provider, use it in your CircleCI pipeline. CircleCI automatically provides OIDC token in the `CIRCLE_OIDC_TOKEN` environment variable. You can use this token to exchange for a Buddy API token:

```yaml
# .circleci/config.yml
version: 2.1

jobs:
  buddy-oidc-test:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          name: Buddy OIDC → /user
          command: |
            set -e

            BUDDY_TOKEN=$(curl -s -X POST "https://api.buddy.works/user/oidc/tokens" \
              -H "Content-Type: application/json" \
              -d "{
                \"provider_id\": \"a2cca468-0e78-43c8-a9aa-cee4b7bf44b9\",
                \"web_identity_token\": \"${CIRCLE_OIDC_TOKEN}\"
              }")

            curl -s -X GET "https://api.buddy.works/user" \
              -H "Authorization: Bearer ${BUDDY_TOKEN}" \
              -H "Content-Type: application/json"

workflows:
  buddy-oidc:
    jobs:
      - buddy-oidc-test
```

## Related documentation

- [Trust Conditions](/docs/api/getting-started/identity-provider/trust-conditions.md) - Trust conditions configuration for CircleCI
- [Supported scopes](/docs/api/getting-started/oauth2/introduction.md#supported-scopes) - Available permissions and scopes


---
Original source: https://buddy.works/docs/api/getting-started/identity-provider/circleci