# Generic OIDC (https://docs.capy.ai/cloud-credentials/oidc)

> Give cloud machines a short-lived OIDC token for any service that accepts a custom OIDC provider.

Use generic OIDC for any service that accepts a custom OIDC provider, such as a secrets manager or a data platform. Capy adds no vendor-specific logic. The machine gets a token for the audience you choose, and the agent passes it to the service in the form that service documents. Read [OIDC federation](/cloud-credentials) first for how the token, the issuer, and refresh work.

## Set up Generic OIDC [#set-up-generic-oidc]

Open **Settings → Cloud credentials → Generic OIDC** and follow these steps. The setup page fills in your issuer URL, organization ID, and project ID, so copy the commands from there. The commands below use placeholders.

<Steps>
  <Step title="Add the project in Capy">
    On **Generic OIDC**, choose **Add project**. Pick the Capy project, then enter the **Audience** your service expects, often its URL or client ID. The audience is 1 to 255 printable characters with no spaces.

    <Screenshot name="cloud-access-oidc-setup" alt="Generic OIDC setup with the project, the audience, and the issuer, audience, and subject values" caption="Enter these three values in your service's OIDC provider settings." />
  </Step>
  <Step title="Trust Capy">
    Add a custom OIDC provider in your service with these values from the page:

    ```yaml
    issuer: <issuer URL>
    audience: <audience>
    subject: org/<org id>/project/<project id>/thread/*
    ```

    Map the subject, or the `org` and `project` claims, to a role in your service.
  </Step>
  <Step title="Verify">
    Choose **Verify**. Capy issues a test token for the audience and shows its subject. Your service checks the token the first time a machine uses it, so a passed check confirms that Capy can sign the token, not that your service accepts it.

    <Screenshot name="cloud-access-oidc-check" alt="Generic OIDC status card with a passed test token, the subject, the audience, and the token file variable" caption="The agent reads the token from the file in CAPY_OIDC_TOKEN_FILE." />
  </Step>
</Steps>

The agent reads the token with `cat "$CAPY_OIDC_TOKEN_FILE"`, for example to pass it in a login request to your service.

## What machines get [#what-machines-get]

| Files in `/etc/capy/cloud-access/` | Exports |
| --- | --- |
| `oidc.jwt` | `CAPY_OIDC_TOKEN_FILE` (`/etc/capy/cloud-access/oidc.jwt`) |

## Revoke access [#revoke-access]

To stop every exchange at once, remove the OIDC provider or its role mapping in your service. To stop Capy from sending tokens, remove the project from **Generic OIDC** in Capy.

## Troubleshooting [#troubleshooting]

A failed check shows the error from Capy and the likely fix. For a machine with no token files, see [OIDC federation troubleshooting](/cloud-credentials#troubleshooting).

<AccordionGroup>
  <Accordion title="Your service rejects the token">A passed check means Capy can sign a token for the audience, not that your service accepts it. Check that the provider's issuer URL matches exactly, with no trailing slash, that its audience matches the **Audience** field, and that the role mapping matches the subject `org/<org id>/project/<project id>/thread/*`.</Accordion>
</AccordionGroup>