> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mountthor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workload identity

> Authenticate CI workloads with OIDC

Use an OIDC principal when a CI system can issue short-lived identity tokens.
Use an [API key](/platform/api-keys) when it cannot.

## Register the workload

```bash theme={null}
mthr principal create \
  --name github-ci \
  --id-provider "https://token.actions.githubusercontent.com" \
  --subject "repo:your-org/your-repo:ref:refs/heads/main" \
  --scope "compute:read,compute:session,compute:write"
```

The issuer, subject, and audience must match the workload token. The default
audience is `api.mountthor.com`.

Run `mthr principal create` with a credential that holds the `principals:write`
and `issuers:write` scopes; a `customer-admin` browser session has them. The
`--scope` values above are the scopes the workload's own sessions receive, not
the scopes required to register it.

## Exchange a token

Set `OIDC_TOKEN` from the CI provider and `TENANT_ID` from
`mthr api request /v1/admin/account`.

```bash theme={null}
printf "%s" "$OIDC_TOKEN" |
  mthr login --tenant "$TENANT_ID" --oidc-token-stdin
```

The CLI stores the short-lived tenant session. Use normal commands:

```bash theme={null}
mthr vm ls --json
```

Exchange a new workload token when the session expires.

## List and delete principals

```bash theme={null}
mthr principal ls
mthr principal delete PRINCIPAL_ID
```

Deleting a principal stops new sessions. Existing sessions keep their expiry.