> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# OIDC trusts

A trust lets the tokens of one OIDC issuer call the API of your organization. The workload stores no CloudRaker key. An admin manages trusts on the [Trusted issuers](https://dash.cloudraker.com/trusted-issuers) page of Dash.

## Create a trust

Select **Add issuer**. Dash has presets for GitHub Actions, GitLab CI, Google Cloud and Kubernetes. Any other issuer with a discovery document works too, if it can send the audience that this page gives. Dash also shows a Microsoft Entra preset, but Entra tokens do not match this API yet.

| Field          | Meaning                                                                      |
| -------------- | ---------------------------------------------------------------------------- |
| Issuer         | The `https` issuer URL. The token `iss` must equal it exactly.               |
| Subject        | The rule for the token `sub`: an exact value or a glob.                      |
| Conditions     | Other claims that the token must have, by name and value.                    |
| Scopes         | The scopes of the token. One or more.                                        |
| Environment    | `live` or `test`.                                                            |
| Limits         | Optional requests per minute for this trust, inside the organization limits. |
| Token lifetime | The lifetime of an exchanged token: 60 to 86400 seconds. The default is 900. |

The audience of the token is always the host of the tenant: `https://{slug}.cloudraker.run`. Configure your issuer to send this audience.

Microsoft Entra cannot send this audience. An Entra v2.0 access token has the client ID of the API as its audience. Entra also accepts an `https` Application ID URI only on a verified domain of your directory. The API refuses these tokens at the [token checks](#token-checks).

**Test a token** in Dash shows which trust matches a token, and why. Dash does not store the token.

## Token checks

The API refuses a token with `401 invalid_token`, or with `400 invalid_grant` on the token endpoint, when one of these checks fails:

* The signature uses RS256 or ES256. The API refuses `none` and every HS algorithm.
* The `iss` equals the issuer of a trust exactly. The issuer publishes a discovery document at `/.well-known/openid-configuration`.
* The `aud` is `https://{slug}.cloudraker.run`.
* The `exp` and `iat` claims are present. `exp - iat` is 24 hours or less. The clock skew allowance is 60 seconds.
* The token is 8 KB or less.

## Exchange a token

Token exchange is the default method. Send the JWT to `POST /v2/oauth/token`. The API returns a short-lived `crt_` token. Use it as a bearer credential on every route.

The endpoint uses RFC 8693 token exchange, and also accepts the RFC 7523 `jwt-bearer` grant. It takes a form body or a JSON body of 16 KB or less. It needs no `Authorization` header.

```bash
curl -s -X POST "https://$CRK_SLUG.cloudraker.run/v2/oauth/token" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
  --data-urlencode "subject_token=$OIDC_TOKEN"
```

```json
{
  "access_token": "crt_…",
  "token_type": "Bearer",
  "expires_in": 900,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "scope": "parse extract jobs:read"
}
```

| Parameter              | Rule                                                                                   |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `grant_type`           | Token exchange or `urn:ietf:params:oauth:grant-type:jwt-bearer`.                       |
| `subject_token`        | The JWT, for token exchange.                                                           |
| `subject_token_type`   | `urn:ietf:params:oauth:token-type:jwt` or `urn:ietf:params:oauth:token-type:id_token`. |
| `assertion`            | The JWT, for `jwt-bearer`.                                                             |
| `audience`, `resource` | Optional. If you send one, it must be the tenant host.                                 |
| `scope`                | Ignored. The token gets the scopes of the trust.                                       |

Errors use the RFC 6749 shape. Read [OAuth errors](/paperwork/v2/errors#oauth-errors).

A change or a delete of a trust revokes its `crt_` tokens. The client then exchanges again.

## Send the OIDC token directly

You can also send the JWT as the bearer credential on any route. The API verifies it and keeps the result in a cache. The cache time is the shortest of `exp`, the token lifetime of the trust and 24 hours.

```bash
curl -s "https://$CRK_SLUG.cloudraker.run/v2/me" \
  -H "Authorization: Bearer $OIDC_TOKEN"
```

Prefer the exchange. Each new JWT needs a verification, and a `crt_` token does not.

## GitHub Actions

The job needs the `id-token: write` permission. The trust subject is, for example, `repo:acme@1234/invoices@5678:ref:refs/heads/main`. GitHub puts the owner ID and the repository ID in the subject. To see the prefix of your repository, run `gh api repos/OWNER/REPO/actions/oidc/customization/sub --jq .sub_claim_prefix`. An older repository can have the prefix `repo:acme/invoices`.

```yaml
permissions:
  id-token: write

steps:
  - name: Parse a file with no stored key
    env:
      AUDIENCE: https://acme.cloudraker.run
    run: |
      ID_TOKEN=$(curl -sf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
        "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUDIENCE" | jq -r .value)
      CRT=$(curl -sf -X POST "$AUDIENCE/v2/oauth/token" \
        --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
        --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
        --data-urlencode "subject_token=$ID_TOKEN" | jq -r .access_token)
      curl -sf -X POST "$AUDIENCE/v2/parse" \
        -H "Authorization: Bearer $CRT" -H "Content-Type: application/json" \
        -H "Prefer: wait=30" \
        -d '{ "file": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf" } }'
```

## Run agents of your organization

Your organization trusts its own Run issuer by default. You do not add a trust for it. A Run agent can call `https://{slug}.cloudraker.run/v2` with no key. Add `oidc` and `scopes` to the host in `agent.yml`. Read [Call the CloudRaker API](https://cloudraker-run.docs.buildwithfern.com/guides/oidc-identity#call-the-cloudraker-api) in the Run docs.

This trust has stricter rules than a normal trust:

* It accepts **agent tokens only**: `identity` must be `agent`, with an `agent` claim. It refuses user tokens.
* It refuses tokens of **branch preview runs**. A token with a `branch` claim gets `401 invalid_token`.
* The token `org` must be the slug of the host, and `iss` must be the issuer of this organization.
* The token scopes come from `agent.yml`, inside a fixed subset.

| Allowed in `agent.yml`                                         | Refused                                        |
| -------------------------------------------------------------- | ---------------------------------------------- |
| The capability scopes, `jobs:read`, `run`, `read` and `cancel` | `admin`, `secrets`, `act_as`, `git`, `preview` |