Workload identity

How it is designed to work

A workload identity provider is an external issuer that your organization trusts: an OIDC issuer (for example a Kubernetes cluster or a CI system), an AWS account, or a SPIFFE trust domain. A role's trust policy names the provider as a Federated principal and pins which workloads of that provider may assume the role. When exchange is available, a workload will present the credential it already has and receive a session of the role, with no Hexel Studio secret to store.

Today you can do every step except the exchange:

1. Register a provider.
2. Name it in a role's trust policy.
3. Test the trust policy with a simulated workload identity.

Providers

oidc config

aws config

spiffe config

Set exactly one of bundle_pem and bundle_endpoint.

Register a provider

POST /v1/workload-identity-providers needs iam:workload_identity_provider:write.

curl -X POST https://api.hexelstudio.com/v1/workload-identity-providers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-actions",
    "type": "oidc",
    "config": {
      "issuer": "https://token.actions.githubusercontent.com",
      "audiences": ["https://sts.hexelstudio.com"]
    }
  }'

The response is 201 Created with the provider:

{
  "id": "wip_...",
  "organization_id": "<org-id>",
  "name": "github-actions",
  "type": "oidc",
  "match_key": "https://token.actions.githubusercontent.com",
  "config": {
    "issuer": "https://token.actions.githubusercontent.com",
    "audiences": ["https://sts.hexelstudio.com"],
    "allowed_algs": ["RS256", "ES256"],
    "max_token_age_seconds": 3600
  },
  "is_enabled": true,
  "created_by_user_id": "<user-id>",
  "created_at": "2026-10-20T09:00:00Z",
  "updated_at": "2026-10-20T09:00:00Z"
}

List, read, update and delete

PATCH takes name, description, config and is_enabled. A new config replaces the old one and is validated again. Setting is_enabled to false also revokes the existing sessions of every role whose trust policy names the provider.

curl -X PATCH https://api.hexelstudio.com/v1/workload-identity-providers/<provider-id> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": false}'

You cannot delete a provider while a role's trust policy names it. The call answers 409 with the roles to change first:

{
  "error": "workload identity provider is referenced by role trust policies",
  "roles": ["<role-id>"]
}

Trust a provider in a role's trust policy

A trust policy statement for workloads uses a federated action, a Federated principal with provider IDs, and a condition that pins the workload. Set the trust policy with PUT /v1/roles/{role_id}/trust-policy, which needs iam:role:write_trust. See Roles for the rest of the trust policy language.

curl -X PUT https://api.hexelstudio.com/v1/roles/<role-id>/trust-policy \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Version": "2026-02-17",
    "Statement": [
      {
        "Sid": "DeployFromMain",
        "Effect": "Allow",
        "Action": "sts:role:assume_with_web_identity",
        "Principal": {"Federated": ["<provider-id>"]},
        "Condition": {
          "StringEquals": {
            "oidc:sub": "repo:acme/api:ref:refs/heads/main",
            "oidc:aud": "https://sts.hexelstudio.com"
          }
        }
      }
    ]
  }'

The trust policy is rejected with 400 ("error": "invalid trust policy" and a problems list) when:

• an Allow statement with a federated action does not pin the key in the table with StringEquals, or with StringLike and a pattern that does not start with * or ?;
• a statement mixes sts:role:assume with a federated action, or a federated action with a User, Group, ServiceUser, Role or Org principal;
• Federated is used without a federated action;
• a provider is not in your organization, or its type does not match the action;
• a principal value contains *.

Condition keys

Operators are StringEquals, StringNotEquals, StringLike, StringNotLike, Bool, ForAnyValue:StringEquals and ForAnyValue:StringLike. In StringLike, * matches any run of characters and ? exactly one. All conditions of a statement must hold; any of the listed values may match. A Deny statement that matches wins over every Allow.

Test a trust policy

POST /v1/roles/{role_id}/trust-policy/simulate runs the same trust decision that role assumption will use, for a workload identity you describe. Nothing is issued or stored. It needs iam:role:read. Add policy to test a draft trust policy before you save it.

curl -X POST https://api.hexelstudio.com/v1/roles/<role-id>/trust-policy/simulate \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": {
      "source": "oidc",
      "issuer": "https://token.actions.githubusercontent.com",
      "subject": "repo:acme/api:ref:refs/heads/main",
      "attributes": {"aud": ["https://sts.hexelstudio.com"]}
    }
  }'

{
  "allowed": true,
  "reason": "trust_allow",
  "role_id": "<role-id>",
  "organization_id": "<org-id>",
  "scope": {"workspace_id": null, "environment_id": null},
  "duration": 3600,
  "matched_statement": "DeployFromMain",
  "provider_id": "<provider-id>",
  "source": {"type": "oidc", "id": "repo:acme/api:ref:refs/heads/main"}
}

When the answer is "allowed": false, reason says why:

The simulation does not check the credential itself: it trusts the identity you send. When exchange is available, the token service will build that identity only after verifying the workload's credential.

What happens if a workload tries to exchange today

The token service at https://sts.hexelstudio.com/token refuses workload credentials:

curl -X POST https://sts.hexelstudio.com/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "<workload-oidc-token>",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "resource": "<role-id>"
  }'

{
  "error": "unsupported_token_type",
  "error_description": "workload identity federation is not enabled yet"
}

The status is 400. The same answer comes back for urn:ietf:params:oauth:token-type:id_token. Token exchange works only with a Hexel Studio access token as subject_token, to assume a role: see Roles.