---
title: "Test whether a principal or workload identity could assume a role"
url: https://hexelstudio.com/docs/api/ciam-iam/roles/simulate
---

# 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: string`

  Role ID

## Headers

- `Authorization: string`

  `Bearer <token>`.

## Body parameters

- `caller: optional 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.

  - `id: optional string`

  - `issued_at: optional integer`

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

  - `org: optional string`

  - `principal_type: optional string`

    user | service_user | role

  - `source: optional SourceIdentity`

    - `id: optional string`

    - `org: optional string`

    - `type: optional string`

      user | service_user | oidc | aws | spiffe

- `identity: optional object`

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

  - `attributes: optional map[array of string]`

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

  - `issuer: optional string`

    oidc issuer, aws account ID, spiffe trust domain

  - `source: optional string`

    oidc | aws | spiffe

  - `subject: optional string`

    oidc sub, aws role ARN, spiffe ID

- `policy: optional object`

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

- `session_name: optional string`

## Returns

`200` OK (`AssumeCheckResponse`)

- `allowed: optional boolean`

- `duration: optional integer`

- `matched_statement: optional string`

- `organization_id: optional string`

- `provider_id: optional string`

- `reason: optional string`

- `role_id: optional string`

- `scope: optional AssumeScope`

  - `environment_id: optional string`

  - `workspace_id: optional string`

- `source: optional SourceIdentity`

  - `id: optional string`

  - `org: optional string`

  - `type: optional string`

    user | service_user | oidc | aws | spiffe

## Errors

- `400` Bad Request
- `404` Not Found

## Example

```bash
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"
}'
```

### Response (200)

```json
{
  "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"
  }
}
```

### Response (400)

```json
{}
```

### Response (404)

```json
{
  "key": "string"
}
```