Workload federation

Feature available with the Enterprise Plan Workload federation lets an external workload exchange the OIDC token issued by its own identity provider for a short-lived Orq.ai API key. No Orq.ai secret is stored in the workload. The key is scoped to one project, carries only the granted permissions, and expires automatically. The name describes what is federated: the identity of a workload (a process that runs without a person), not the identity of the workspace. Orq.ai is the side that trusts the external issuer here. Related pages:

Single Sign-On covers member login with OIDC or SAML and SCIM provisioning. Workload federation is for machine identities, not for people signing in.
Session identity tokens covers the reverse direction, where Orq.ai issues OIDC tokens that AWS, Google Cloud, Vault, and other relying parties verify.

Use cases

A workload is any process that calls Orq.ai with no person driving it, authenticating with an identity its own platform already issues. It is not an Orq.ai API key, and it is not a person signed in to the dashboard. A CI/CD job, a scheduled batch job, a backend service, a long-running application, or a deploy pipeline all qualify.

The issuer’s discovery document must be reachable from the public internet, so an in-cluster Kubernetes issuer works only when it is published that way.

If the process would otherwise need an Orq.ai credential stored and rotated, it is a candidate for federation. If a person signs in, use Single Sign-On. Each case below needs one trust configuration: an issuer, claim rules that narrow who may exchange, and the permissions the job uses.

Run evaluations from CI. A GitHub Actions workflow on one repository’s main branch, bound to repository_id and ref.
Sync Prompts from a pipeline. A GitLab CI pipeline bound to project_id and ref.
Call the AI Gateway from a service. A backend service behind Keycloak, Okta, Auth0, or Microsoft Entra ID, bound to its azp or appid.
Reach the production Deployment only from a protected environment. A pipeline bound to repository_id and environment.
Export usage on a schedule. A Read only trust that cannot create or change anything.

Set up GitHub Actions step by step walks the first case end to end, and every granted exchange is recorded under Settings > Organization > Audit logs.

How it works

The workload asks its identity provider for an OIDC token with a specific aud (audience) value.
The workload sends that token to the Orq.ai token exchange endpoint.
Orq.ai finds the trust configuration matching the token’s issuer and audience, verifies the signature against the issuer’s published keys, and checks the token’s claims against the configured rules.
Orq.ai returns a short-lived API key limited to the permissions and project on the trust configuration.
The workload uses the key as a normal Bearer token until it expires.

The only values the two sides have to agree on are public: the issuer URL and the audience. The subject token itself stays the credential and is sent only to the exchange endpoint.

Prerequisites

A workspace on the Enterprise plan. Configuring SSO first is not required.
Workspace admin rights to manage trust configurations.
An identity provider that issues OIDC JWTs and publishes its signing keys through OpenID discovery. The discovery document and signing keys must be reachable from the public internet.
Workload federation is tested with GitHub Actions (including GitHub Enterprise Server) and Keycloak. Other providers such as GitLab CI, Okta, Auth0, and Microsoft Entra ID work when their tokens meet the requirements under Exchange a token.

Create a trust configuration

Go to Settings > Organization > Workload federation and click Add trust configuration.

Field	Description
Name	A label, for example `GitHub Actions CI`.
Issuer URL	The OIDC issuer of the identity provider, exactly as it appears in the token’s `iss` claim. Must use `https` and have no trailing slash. Examples: `https://token.actions.githubusercontent.com` for GitHub Actions, `https://<github-host>/_services/token` for GitHub Enterprise Server.
Audience	The value the workload must request as `aud`. The field is prefilled with a unique value; keep it unless the identity provider requires a specific one. Copy it into the workload. It cannot be changed after creation; for a different audience, create a new trust configuration.
Expires after	Lifetime of each minted key, 1 to 60 minutes. Default 60 minutes.
Project	Every minted key is pinned to this project.
Permissions	`All`, `Restricted`, or `Read only`. Restricted opens the same permission picker used for API keys, limited to the permissions a project-scoped key can hold. Workspace administration permissions (members, billing, SSO, groups, workspace settings) and identity permissions (identities, SCIM) cannot be granted to a workload.
Claim rules	Which tokens from this issuer are accepted. See Claim rules.

An existing configuration can be disabled from its edit view to stop exchanges without deleting it.

An issuer and audience pair can belong to only one enabled trust configuration across all of Orq.ai. If a pair is already in use, the configuration is refused; keep the generated audience to avoid this.

Any change to a trust configuration, including renaming it, changing its lifetime, or turning it off, revokes every key it has already minted. Deleting a trust configuration revokes all of its keys. Workloads obtain a new key on their next exchange.

Set up GitHub Actions step by step

This walkthrough lets the main branch of the acme/evals repository call the AI Gateway.

Find the repository’s numeric ID using any of these:
- Browser (public repositories): open https://api.github.com/repos/acme/evals and copy the top-level "id" value.
- GitHub CLI (public or private): gh api repos/acme/evals --jq .id
- From a workflow run: add a step with echo "${{ github.repository_id }}". Use github.repository_owner_id for the organization ID.
Example result: 812345678. Replace acme/evals with the target repository.

In Orq.ai, go to Settings > Organization > Workload federation, click Add trust configuration, and fill in:

Field	Value
Name	`acme/evals main`
Issuer URL	`https://token.actions.githubusercontent.com`
Audience	Keep the generated value and copy it
Expires after	`60` (the default)
Project	The project the workflow works in, for example `Evals`
Permissions	`Restricted`, with Chat completions granted
Claim rules	One rule with two conditions: `repository_id` = `812345678` and `ref` = `refs/heads/main`

In the GitHub repository, go to Settings > Secrets and variables > Actions > Variables and add a repository variable ORQ_AUDIENCE with the copied audience. The audience is not a secret, so a variable is enough.
Add the workflow from GitHub Actions to .github/workflows/.
Push to main. The job exchanges its GitHub token for an Orq.ai API key and calls the AI Gateway. The exchange appears in Settings > Organization > Audit logs as federation.exchange.granted, with the token subject.

If the exchange step fails with invalid_target, see Troubleshooting.

Claim rules

A rule is a list of conditions. A token is accepted when every condition of any single rule matches. Rules are combined with OR, conditions within a rule with AND. Each condition names a claim and lists its allowed values:

A value without * must match the claim exactly.
A value containing * is a glob anchored at both ends. * matches any characters except :, so repo:acme/*:ref:refs/heads/main cannot be widened by a token whose sub contains extra : segments.
A missing claim, or a claim that is not a string, fails the condition.

A trust configuration holds up to 20 rules, each with up to 20 conditions, each with up to 50 values. Rules decide which tokens are accepted. The issuer and audience only prove that the token came from the right provider; the rules narrow it down to a specific repository, branch, environment, user, or application.

A rule that is too broad hands out keys to everything that provider signs tokens for. Start narrow and widen only when needed.

Which claims to use

Every OIDC provider puts different claims in its tokens. The ones that identify a workload or a person:

Provider	Claims commonly used in rules
GitHub Actions	`repository_id`, `repository_owner_id`, `repository`, `ref`, `environment`, `actor`, `event_name`, `workflow`
GitLab CI	`project_id`, `namespace_path`, `ref`, `user_login`
Keycloak, Okta, Auth0	`sub`, `preferred_username`, `email`, `azp`
Microsoft Entra ID	`sub`, `preferred_username`, `upn`, `appid`

To see the exact claims and values a provider sends, decode one of its tokens before writing rules:

jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | . + "=" * ((4 - length % 4) % 4) | @base64d | fromjson' <<< "${TOKEN}"

A live subject token is the credential itself, so decode it locally. An already-expired token is safe to paste into an online decoder such as jwt.io, and nothing needs decoding on the Orq.ai side: the exchange endpoint verifies the signature itself.

Claim names are case-sensitive, and a rule on a claim the provider does not send never matches.

Common rules

Goal	Conditions in one rule
Only one repository, any branch	`repository_id` = `123456789`
Only the main branch of one repository	`repository_id` = `123456789` and `ref` = `refs/heads/main`
Only release tags of one repository	`repository_id` = `123456789` and `ref` = `refs/tags/v*`
Only the `production` environment of one repository	`repository_id` = `123456789` and `environment` = `production`
Only workflows triggered by one person	`repository_id` = `123456789` and `actor` = `jane-doe`
Every repository in one GitHub organization	`repository_owner_id` = `987654`
Only one Keycloak or Okta user	`email` = `jane@example.com`
Only one Keycloak or Okta application	`azp` = `ci-runner`

Conditions in the same rule are ANDed, so each row above accepts only tokens that satisfy every condition in it.

To allow alternatives, add a rule per alternative. To accept two repositories, create two rules, each binding its own repository_id; a token from either repository matches one of them and is accepted.
To allow several values in one condition, list them. ref with refs/heads/main and refs/heads/release accepts a token from either branch.

GitHub Actions rules

GitHub Actions tokens have two additional requirements. Bind a numeric ID. Every rule must bind repository_id or repository_owner_id to a value without *. Repository and organization names can be renamed or transferred; the numeric IDs cannot. To find them:

Open https://api.github.com/repos/<owner>/<repo> for a public repository, or run gh api repos/<owner>/<repo> --jq .id. The organization ID is .owner.id in the same response.
Inside a workflow, ${{ github.repository_id }} and ${{ github.repository_owner_id }} print the exact values the token carries.

Restrict the events. These events are accepted:

push, workflow_dispatch, schedule, release, create, deployment, deployment_status.

Any other event, such as pull_request from a fork or a merge queue, is rejected unless every rule has an event_name condition with exact values. A value containing * does not count.

To accept pull request workflows on purpose, add an event_name condition to each rule and list every accepted event, for example push and pull_request. A rule with only event_name = pull_request rejects tokens from pushes.

Exchange a token

The exchange endpoint implements OAuth 2.0 Token Exchange (RFC 8693).

POST https://my.orq.ai/v2/auth/federation/token
Content-Type: application/x-www-form-urlencoded

Parameter	Value
`grant_type`	`urn:ietf:params:oauth:grant-type:token-exchange`
`subject_token_type`	`urn:ietf:params:oauth:token-type:jwt` or `urn:ietf:params:oauth:token-type:id_token`
`subject_token`	The OIDC token from the identity provider
`audience`	The audience shown on the trust configuration

No Orq.ai credential is sent. The subject token is the credential. A successful response returns the key:

{
  "access_token": "sk-orq-...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

expires_in is the lifetime configured on the trust configuration, independent of the subject token’s own expiry. The subject token must:

Be signed by the issuer’s current keys, with iss equal to the trust configuration’s issuer URL.
Contain the trust configuration’s audience in aud.
Have been issued (iat) within the last 10 minutes.
Carry a jti claim. Each token can be exchanged once.

Errors

HTTP	`error`	Meaning
400	`invalid_request`	A parameter is missing or malformed.
400	`invalid_target`	The token was not accepted: no matching trust configuration, signature or audience mismatch, claim rules not met, token stale or already exchanged, or workspace not entitled. The specific reason is not returned. See Troubleshooting.
429	`slow_down`	More than 60 exchanges per minute on one trust configuration.
503	`temporarily_unavailable`	Orq.ai could not complete the exchange. Retry with a new subject token.

Use the key

The minted key is a standard Orq.ai API key.

Send it as Authorization: Bearer <key> to the platform API, the AI Gateway, and an MCP Gateway.
Scope: the granted permissions and the pinned project only.
Lifetime: it stops working when it expires.
Audit: each grant is recorded as federation.exchange.granted, with the trust configuration, the token subject, the key ID, and its expiry.

Examples

GitHub Actions

name: call-orq

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  run:
    runs-on: ubuntu-latest
    env:
      ORQ_AUDIENCE: ${{ vars.ORQ_AUDIENCE }}
    steps:
      - name: Exchange the GitHub token for an Orq.ai API key
        run: |
          subject_token=$(curl -sS \
            "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=${ORQ_AUDIENCE}" \
            -H "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" | jq -r .value)

          response=$(curl -sS -X POST https://my.orq.ai/v2/auth/federation/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=${subject_token}" \
            --data-urlencode "audience=${ORQ_AUDIENCE}")

          orq_api_key=$(jq -r '.access_token // empty' <<< "${response}")
          if [ -z "${orq_api_key}" ]; then
            echo "Token exchange failed: $(jq -r '.error // .error_description // "unparseable exchange response"' <<< "${response}" 2>/dev/null || echo "unparseable exchange response")"
            exit 1
          fi

          echo "::add-mask::${orq_api_key}"
          echo "ORQ_API_KEY=${orq_api_key}" >> "$GITHUB_ENV"

      - name: Call the AI Gateway with the Orq.ai CLI
        env:
          ORQ_NO_INPUT: 1
        run: |
          npm install -g @orq-ai/cli
          orq chat create \
            --model openai/gpt-5.4-mini \
            --messages '[{"role": "user", "content": "Write a professional email"}]' \
            -o json -j 'choices[0].message.content' --raw

The exchange step exports the minted key as ORQ_API_KEY, so every later step uses it exactly as it would a stored API key.

The CLI reads ORQ_API_KEY directly. ORQ_NO_INPUT=1 makes it fail instead of prompting, so a misconfigured job errors out rather than hanging.
The SDKs read the same variable. The step can just as well be a script using the Node SDK (@orq-ai/node) or the Python SDK (orq-ai-sdk).
id-token: write is required. Without it, GitHub does not issue an OIDC token to the job.

ORQ_AUDIENCE is the repository variable from Set up GitHub Actions step by step.

The trust configuration for this workflow uses issuer https://token.actions.githubusercontent.com, one rule with repository_id set to the repository’s numeric ID and ref set to refs/heads/main, and grants the Chat completions permission.

Keycloak

Orq.ai reads the audience from the ID token, not the access token.

In Keycloak, open the client the workload uses, then make the ID token carry the audience:
- Simplest: create the trust configuration with the client ID as its audience, because Keycloak already puts the client ID in the ID token’s aud.
- Explicit: add an Audience mapper to the client with Included Custom Audience set to the trust configuration’s audience and Add to ID token turned on.
Create a trust configuration with issuer https://<keycloak-host>/realms/<realm> and a rule that limits who may exchange, for example azp = <client-id> for one application or email = jane@example.com for one user.

Request tokens with scope=openid so Keycloak returns an ID token, then exchange it:

curl -sS -X POST https://my.orq.ai/v2/auth/federation/token \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
  --data-urlencode "subject_token=${ID_TOKEN}" \
  --data-urlencode "audience=${ORQ_AUDIENCE}"

Other OIDC providers

Request an ID token from the provider with the trust configuration’s audience in aud, then send it to the exchange endpoint as shown above. Add a rule on a claim such as preferred_username, email, or sub to limit which principals may exchange tokens.

Troubleshooting

Every token rejection returns the same invalid_target error. Open Settings > Organization > Audit logs and look for federation.exchange.denied on the trust configuration. The reason names what to fix:

Reason	Fix
`claims_rejected`	The token does not satisfy any rule. Decode the token and compare its claims with the rules. For GitHub Actions, also check the event: see GitHub Actions rules.
`subject_token_stale`	The token was issued more than 10 minutes ago. Request a new token right before the exchange.
`subject_token_replayed`	The token was already exchanged. Request a new token for each exchange.
`missing_jti`	The provider does not include a `jti` claim. Configure it to, or use a different token type.
`trust_config_superseded`	The trust configuration changed while the exchange was running. Request a new token and retry.
`trust_config_ttl_invalid`	The configured lifetime is below 30 seconds. Raise Expires after to between 1 and 60 minutes.

If no denied entry appears, Orq.ai could not link the token to a trust configuration, could not verify it, or the per-trust denial-audit budget was exhausted. Check that:

The token’s iss exactly matches the Issuer URL, including the scheme and without a trailing slash.
The token’s aud contains the trust configuration’s audience, and the same audience is sent in the audience parameter.
The issuer’s discovery document and signing keys are reachable from the public internet, and the token is signed with one of those keys.
The trust configuration is enabled.
The workspace is on the Enterprise plan.

Security

Token rejections return the same generic error, so a caller cannot discover which issuers or audiences are configured.
Each subject token can be exchanged once. Replays are rejected.
Subject tokens older than 10 minutes are rejected regardless of their own expiry.
Exchanges are limited to 60 per minute per trust configuration.
Granted exchanges, and denials of correctly signed tokens meant for a trust configuration, are recorded in the workspace audit log. Denials are capped at 20 per minute per trust configuration.
Keys minted from a configuration created in the dashboard are pinned to its project, and no minted key can hold workspace administration permissions.
Issuer discovery and key fetches refuse redirects.

Limitations

A workspace holds up to 100 trust configurations.
Trust configurations are managed by workspace admins from the dashboard. They cannot be created or edited with an API key.
The trust configuration’s audience must appear in the token’s aud. If the identity provider cannot add a custom value, use a value it already sends, such as the client ID, as long as no other trust configuration uses the same issuer and audience.
Identity providers on a private network are not supported. Orq.ai must be able to fetch the issuer’s discovery document and signing keys over the public internet.

Workspace & Projects

Identity & Access

Billing & Usage

Security & Compliance

Enterprise Deployment

Use cases

How it works

Prerequisites

Create a trust configuration

Set up GitHub Actions step by step

Claim rules

Which claims to use

Common rules

GitHub Actions rules

Exchange a token

Errors

Use the key

Examples

GitHub Actions

Keycloak

Other OIDC providers

Troubleshooting

Security

Limitations

​Use cases

​How it works

​Prerequisites

​Create a trust configuration

​Set up GitHub Actions step by step

​Claim rules

​Which claims to use

​Common rules

​GitHub Actions rules

​Exchange a token

​Errors

​Use the key

​Examples

​GitHub Actions

​Keycloak

​Other OIDC providers

​Troubleshooting

​Security

​Limitations

Use cases

How it works

Prerequisites

Create a trust configuration

Set up GitHub Actions step by step

Claim rules

Which claims to use

Common rules

GitHub Actions rules

Exchange a token

Errors

Use the key

Examples

GitHub Actions

Keycloak

Other OIDC providers

Troubleshooting

Security

Limitations