Hexel StudioDocs

Test whether a principal or workload identity could assume a role

POST/roles/{role_id}/trust-policy/simulate

Runs the same decision as role assumption without minting a session or changing anything. Pass a draft trust policy in policy to test it before saving. The simulated caller must belong to the role's organization; a role caller is simulated as a fresh one-hour session.

Path parameters

Role ID

Headers

Authorizationstring

Bearer <token>.

Body parameters

Simulation

calleroptional object

Caller is a principal of the role's organization (principal_type user, service_user or role, and id). Exactly one of Caller or Identity.

5 properties of object

idoptional string

issued_atoptional integer

IssuedAt (Unix seconds) of the caller's token; checked against role revocation when chaining.

orgoptional string

principal_typeoptional string

user | service_user | role

sourceoptional SourceIdentity

3 properties of SourceIdentity

idoptional string

orgoptional string

typeoptional string

user | service_user | oidc | aws | spiffe

identityoptional object

Identity is a verified workload identity as STS would present it.

4 properties of object

attributesoptional map[array of string]

Attributes: oidc string/array claims; aws principal_type, user_id; spiffe path.

issueroptional string

oidc issuer, aws account ID, spiffe trust domain

sourceoptional string

oidc | aws | spiffe

subjectoptional string

oidc sub, aws role ARN, spiffe ID

policyoptional object

Policy is a draft trust policy; empty uses the role's stored policy.

session_nameoptional string

Returns

200OKAssumeCheckResponse

allowedoptional boolean

durationoptional integer

matched_statementoptional string

organization_idoptional string

provider_idoptional string

reasonoptional string

role_idoptional string

scopeoptional AssumeScope

2 properties of AssumeScope

environment_idoptional string

workspace_idoptional string

sourceoptional SourceIdentity

3 properties of SourceIdentity

idoptional string

orgoptional string

typeoptional string

user | service_user | oidc | aws | spiffe

Errors

400Bad Request
404Not Found

POST Request

curl --request POST \
  --url 'https://api.hexelstudio.com/v1/roles/{role_id}/trust-policy/simulate' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "caller": {
    "id": "string",
    "issued_at": 0,
    "org": "string",
    "principal_type": "string",
    "source": {
      "id": "string",
      "org": "string",
      "type": "string"
    }
  },
  "identity": {
    "attributes": {
      "key": [
        "string"
      ]
    },
    "issuer": "string",
    "source": "string",
    "subject": "string"
  },
  "policy": {},
  "session_name": "string"
}'

const res = await fetch("https://api.hexelstudio.com/v1/roles/{role_id}/trust-policy/simulate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "caller": {
      "id": "string",
      "issued_at": 0,
      "org": "string",
      "principal_type": "string",
      "source": {
        "id": "string",
        "org": "string",
        "type": "string"
      }
    },
    "identity": {
      "attributes": {
        "key": [
          "string"
        ]
      },
      "issuer": "string",
      "source": "string",
      "subject": "string"
    },
    "policy": {},
    "session_name": "string"
  }),
})
const data = await res.json()

import os
import requests

res = requests.post(
    "https://api.hexelstudio.com/v1/roles/{role_id}/trust-policy/simulate",
    headers={"Authorization": f"Bearer {os.environ['ACCESS_TOKEN']}"},
    json={
        "caller": {
            "id": "string",
            "issued_at": 0,
            "org": "string",
            "principal_type": "string",
            "source": {
                "id": "string",
                "org": "string",
                "type": "string",
            },
        },
        "identity": {
            "attributes": {
                "key": [
                    "string",
                ],
            },
            "issuer": "string",
            "source": "string",
            "subject": "string",
        },
        "policy": {},
        "session_name": "string",
    },
)
data = res.json()

Response

{
  "allowed": true,
  "duration": 0,
  "matched_statement": "string",
  "organization_id": "string",
  "provider_id": "string",
  "reason": "string",
  "role_id": "string",
  "scope": {
    "environment_id": "string",
    "workspace_id": "string"
  },
  "source": {
    "id": "string",
    "org": "string",
    "type": "string"
  }
}

{}

{
  "key": "string"
}