Delegated Sessions In development

Delegated sessions let one caller assume a role for a limited time. They are useful when a human, service account, or agent needs temporary access without permanently assigning a role.

Common use cases:

• Support engineer assumes a customer-support role for one tenant.
• Service account performs a scoped maintenance task.
• Automation agent receives a short-lived capability instead of a long-lived admin role.

SaaSLayer Permissions also supports two newer session shapes:

• Federated principal auth for workloads that authenticate as themselves via OIDC, AWS IAM, or Kubernetes — no role assumption involved.
• Agent delegation for agents acting on behalf of users, with actingFor metadata and permission intersection rather than role assumption.

The role-assumption pattern documented on this page is still supported and is the right choice when "borrow a role for a short window" is exactly what you want.

Assumable roles

A role must have a trust policy before it can be assumed. The trust policy defines who may assume it and for how long.

At a high level:

{
  "id": "role-support-viewer",
  "trustPolicy": {
    "maxSessionDuration": 3600,
    "preserveCallerBoundaries": true
  }
}

Trust policy details are part of role configuration. A role without a trust policy is not assumable.

Create a session

POST /sessions/assume
Content-Type: application/json

{
  "callerId": "user-support-1",
  "callerType": "user",
  "roleId": "role-support-viewer",
  "scope": "tenant-acme-prod",
  "durationSeconds": 1800
}

Example response:

{
  "data": {
    "type": "session",
    "id": "sess_01h...",
    "attributes": {
      "token": "eyJ...",
      "callerId": "user-support-1",
      "callerType": "user",
      "assumedRoleId": "role-support-viewer",
      "scope": "tenant-acme-prod",
      "status": "active",
      "expiresAt": "2026-05-06T12:30:00.000Z"
    }
  }
}

If session token minting is configured, the response includes a JWT token. Use that token for authorized API calls that should run under the session.

Restrict with a session policy

A session policy further narrows the assumed role.

{
  "callerId": "user-support-1",
  "callerType": "user",
  "roleId": "role-support-admin",
  "scope": "tenant-acme-prod",
  "durationSeconds": 1800,
  "sessionPolicy": {
    "statements": [
      {
        "effect": "can",
        "actions": ["read", "list"],
        "resources": ["*"]
      }
    ]
  }
}

Session policies can only reduce access. They do not grant permissions outside the assumed role.

Revoke a session

POST /sessions/sess_01h.../revoke
Content-Type: application/json

{
  "revokedBy": "user-admin",
  "reason": "Support case closed"
}

Revocation writes a marker so future token checks can reject the session.

Operational guidance

• Use short durations by default.
• Scope support sessions to one tenant whenever possible.
• Preserve caller boundaries for sensitive roles.
• Log the business reason for session creation in your surrounding workflow.
• Prefer sessions over temporary permanent role assignments.
• Revoke sessions when the support case, automation run, or incident is complete.