Skip to navigation

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

Provider typeExternal credentialTrust configuration
OIDCA signed JWT from AWS, Azure, GitHub Actions, Google Cloud, Kubernetes, SPIFFE/SPIRE, Vercel, or another OIDC-compatible issuerExact issuer URI, one or more audiences, and OIDC discovery or a static public JWKS
X.509A client certificate presented during TLSRoot CA trust anchors and optional intermediate CA certificates

Choose a setup guide for your workload:

Configure a provider

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

Open Workload Identity in the Mixlayer console and select New provider.

Configure these sections:

  1. General settings: Give the provider a descriptive name, choose OIDC or X.509, and choose whether it accepts exchanges.
  2. Provider trust configuration: Enter the OIDC issuer and audiences or the X.509 CA certificates.
  3. Attribute transformations: Map verified credential values into mixlayer.subject, mixlayer.groups, or attribute.* values.
  4. Admission condition: Optionally reject credentials before authorization.
  5. Permissions: Set the fallback permissions. Add ordered authorization rules after creating the provider when different workloads need different permissions.

Use Test rules with a representative assertion before enabling a provider. Policy tests evaluate transformations, admission, and authorization without issuing a credential.

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. They cannot read the result of other transformations. If mixlayer.groups is omitted, Mixlayer uses an empty list. Custom attribute.* values can be scalars or lists of scalars, including booleans, numbers, strings, and null. Nested maps and nested lists are not valid transformation results.

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:

PermissionGrants
inferenceCalls to Mixlayer model inference APIs
api-readRead access to Platform API resources
api-writeapi-read plus non-administrative Platform API writes
api-adminAdministrative Platform API operations; also includes api-read and api-write

api-admin does not imply inference.

CEL policy support

Use Common Expression Language (CEL) to map identity attributes, restrict admission, and define authorization conditions. The values an expression can read and the type it must return depend on where you use it:

ExpressionCan readMust return
Attribute transformationassertionA non-empty string for mixlayer.subject; a list of strings for mixlayer.groups; a scalar value or list of scalar values for attribute.*
Admission conditionassertion, mixlayer, attributetrue or false
Authorization conditionmixlayer, attributetrue or false

Mixlayer supports a subset of CEL. You can read fields and list or map entries, write literal values, compare values, use arithmetic and boolean operators, check membership with in, and choose between values with condition ? value : fallback.

Supported functions include has, size, the string functions contains, startsWith, endsWith, and matches, and type conversions such as string. Additional CEL libraries and user-defined functions are not supported.

Common expressions

Exact common-name match:

assertion.subject.common_name == "production-model-client"

Check a scalar before reading it:

has(assertion.subject.organization) &&
assertion.subject.organization == "Example, Inc."

Check list membership:

"Production" in assertion.subject.organizational_units

Search typed SAN entries:

assertion.subject_alt_names.exists(san,
san.type == "DNS" && san.value.endsWith(".example.com"))

Map a boolean for use in authorization:

attribute.production = assertion.subject.organizational_units.exists(ou, ou == "Production")

Then an authorization rule can use attribute.production == true. It cannot read the original certificate or JWT claims directly.

Bounded searches

collection.exists(item, predicate) returns true if any entry matches. An empty collection returns false. Lists iterate over values; maps iterate over keys. The two-variable form, collection.exists(key, value, predicate), is also supported; for lists the first variable is the index. Evaluation can stop after a match.

The collection must be a direct input path under a root available at that policy stage, or a bounded list or map literal. For example, assertion.subject_alt_names, assertion["subject"].organizational_units, and ["production", "staging"] are valid ranges. Path indexes must be literal strings or integers.

Nested exists calls and computed ranges such as (assertion.groups + assertion.groups).exists(...) are rejected. Other comprehension macros, including all, map, filter, and exists_one, are not enabled. CEL bindings such as cel.bind are not enabled. exists searches values; it does not return the matching value or transform a list.

A missing field, wrong runtime type, or other evaluation error rejects the exchange if the expression’s final result is an error. CEL short-circuit and logical error-handling rules apply: a successful exists match can determine the result even if another entry would cause an error. Use has and type checks when optional data is expected.

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:

file=exchange-workload-identity-token.sh
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:

file=call-mixlayer-with-workload-token.sh
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.