Workload Identity Federation

Workload identity federation lets automated services authenticate to Mixlayer without storing a long-lived API key. The workload presents a short-lived OIDC token or X.509 certificate, and Mixlayer exchanges it for a short-lived access token.

Use workload identity federation for production services, deployment pipelines, and other automated workloads that can obtain an OIDC token or an X.509 client certificate. Continue using an API key for local development or environments without a workload identity.

How it works

1. An organization owner creates a workload identity provider that trusts an external OIDC issuer or certificate authority.
2. The provider transforms credential claims into a required mixlayer.subject, optional mixlayer.groups, and custom attribute.* values.
3. An optional admission condition rejects identities that should not authenticate.
4. Mixlayer evaluates authorization rules in order. The first matching rule supplies the complete permission set.
5. The workload exchanges its external credential for a short-lived Mixlayer bearer token.
6. The workload uses that bearer token with https://mixlayer.ai or https://api.mixlayer.com.

The final authorization rule is always the unconditional fallback condition true. Permissions are not merged between rules.

Choose a provider type

Choose a setup guide for your workload:

• AWS
• Azure
• GitHub Actions
• Google Cloud
• Kubernetes
• SPIFFE / SPIRE
• Vercel
• X.509 certificates

Configure a provider

You must be an organization owner or use a machine credential with api-admin to create or change providers.

Map identity attributes

Attribute transformations are CEL expressions evaluated against the verified external credential. Every provider must produce a non-empty string at mixlayer.subject.

mixlayer.subject       = assertion.sub
mixlayer.groups        = assertion.groups
attribute.environment = assertion.environment

Transformations can read only assertion.* values and are evaluated independently. If mixlayer.groups is omitted, Mixlayer uses an empty list.

OIDC assertions include the verified iss, sub, aud, exp, and iat claims plus other claims from the JWT. X.509 assertions are described in the X.509 guide.

Restrict admission

An admission condition can read assertion.*, mixlayer.*, and attribute.*. Use it to reject identities that should receive no Mixlayer access, especially when trusting a shared issuer such as GitHub Actions.

attribute.repository_owner_id == "12345678" &&
attribute.repository_id == "87654321"

A false result or evaluation error rejects the exchange.

Assign permissions

Authorization conditions can read normalized mixlayer.subject, mixlayer.groups, and attribute.* values. They cannot read raw assertion.* claims; map an authorization-relevant claim first.

[
  {
    "condition": "attribute.environment == \"production\"",
    "permissions": ["api-read", "inference"]
  },
  {
    "condition": "true",
    "permissions": ["inference"]
  }
]

Evaluation stops at the first match. Its permissions are the complete result; later rules are not evaluated or merged. To deny an identity entirely, reject it in the admission condition.

The available permissions are the same as for API keys:

api-admin does not imply inference.

Exchange an OIDC token

Set the provider ID returned when you created the provider and obtain a current JWT from your workload environment:

export MIXLAYER_IDENTITY_PROVIDER_ID="wi_..."
export MIXLAYER_SUBJECT_TOKEN="..."

Exchange it for a Mixlayer access token:

MIXLAYER_ACCESS_TOKEN=$(
  jq -n \
    --arg provider "$MIXLAYER_IDENTITY_PROVIDER_ID" \
    --arg token "$MIXLAYER_SUBJECT_TOKEN" \
    '{
      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
      subject_token_type: "urn:ietf:params:oauth:token-type:jwt",
      subject_token: $token,
      identity_provider_id: $provider
    }' |
  curl --fail-with-body --silent --show-error \
    https://api.mixlayer.com/v1/workload_identity/token \
    -H "Content-Type: application/json" \
    --data-binary @- |
  jq -er .access_token
)

Use the resulting token like an API key:

curl https://mixlayer.ai/v1/chat/completions \
  -H "Authorization: Bearer $MIXLAYER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.5-4b-free",
    "messages": [{"role": "user", "content": "Hello from a federated workload"}]
  }'

Mixlayer does not return a refresh token. The access token lasts for at most one hour and never outlives the external JWT or X.509 certificate. Reuse it until shortly before expiry, then obtain a new external credential and exchange again.

Operate providers safely

• Use a separate provider for each issuer and trust boundary.
• Use a dedicated audience such as https://api.mixlayer.com rather than an audience shared with unrelated services.
• Prefer stable, immutable subject identifiers.
• Grant only the permissions the workload needs.
• Keep clocks synchronized so short-lived credentials pass iat, nbf, and exp validation.
• Do not log external credentials, Mixlayer access tokens, certificates, or private keys.
• Deactivate a provider to stop new exchanges. Provider policy changes also invalidate tokens issued under the previous policy revision; inference services may take up to one minute to observe the change.

If an exchange fails, compare the credential’s issuer, audience, subject, expiry, and signing key with the provider. Then test the same assertion against the provider policy to find transformation, admission, or rule errors.