---
title: "Preview a member role change"
method: GET
path: "/identity/members/{id}/role_previews"
tags: ["identity", "members", "business", "customer-session"]
---

# Preview a member role change

`GET /identity/members/{id}/role_previews`

## Request

- Base URL: `https://api.stablesea.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stablesea.com/identity/members/{id}/role_previews`
- Auth: none declared

Returns capability gains and losses and the expected revision required to save the role assignment. Requires roles_manage in a business that uses roles.

## Path parameters

- `id` string, required

## Query parameters

- `role_kind` 'preset' | 'custom', required
- `role_key` string, required

## Response `200`

OK

- MembersroleAssignmentPreviewOutput
  - `assignment_revision` integer, required
  - `current_role` AccessRole, nullable, required
    - `id` string, required: A preset's name, such as admin, or a custom role's id.
    - `kind` 'preset' | 'custom', required
    - `name` string, required: The role's name as members read it.
    - `revision` integer, required: The role revision whose capabilities apply.
  - `current_role_migrated` boolean, required: Whether the current assignment was recorded by the legacy migration.
  - `expected_revision` string, required
  - `gained` MembersroleAssignmentAtomChanges, required
    - `administering` MembersroleAssignmentAtom[], required
      - `atom` 'payments_read' | 'payees_read' | 'payee_details_read' | 'investments_read' | 'automations_read' | 'reports_read' | 'statements_generate' | 'funds_deposit' | 'funds_withdraw' | 'assets_buy' | 'assets_sell' | 'bank_account_add' | 'bank_account_remove' | 'wallet_add' | 'automations_manage' | 'transfers_approve' | 'approval_controls_manage' | 'integrations_manage' | 'kyb_read' | 'kyb_edit' | 'kyb_submit' | 'documents_read' | 'documents_manage' | 'messages_read' | 'messages_send' | 'agreements_read' | 'agreements_sign' | 'audit_read' | 'members_read' | 'members_invite' | 'roles_manage' | 'networks_manage' | 'signers_manage' | 'api_keys_manage', required
      - `group` string, required
    - `performing` MembersroleAssignmentAtom[], required
      - `atom` 'payments_read' | 'payees_read' | 'payee_details_read' | 'investments_read' | 'automations_read' | 'reports_read' | 'statements_generate' | 'funds_deposit' | 'funds_withdraw' | 'assets_buy' | 'assets_sell' | 'bank_account_add' | 'bank_account_remove' | 'wallet_add' | 'automations_manage' | 'transfers_approve' | 'approval_controls_manage' | 'integrations_manage' | 'kyb_read' | 'kyb_edit' | 'kyb_submit' | 'documents_read' | 'documents_manage' | 'messages_read' | 'messages_send' | 'agreements_read' | 'agreements_sign' | 'audit_read' | 'members_read' | 'members_invite' | 'roles_manage' | 'networks_manage' | 'signers_manage' | 'api_keys_manage', required
      - `group` string, required
  - `lost` MembersroleAssignmentAtomChanges, required
    - `administering` MembersroleAssignmentAtom[], required
      - `atom` 'payments_read' | 'payees_read' | 'payee_details_read' | 'investments_read' | 'automations_read' | 'reports_read' | 'statements_generate' | 'funds_deposit' | 'funds_withdraw' | 'assets_buy' | 'assets_sell' | 'bank_account_add' | 'bank_account_remove' | 'wallet_add' | 'automations_manage' | 'transfers_approve' | 'approval_controls_manage' | 'integrations_manage' | 'kyb_read' | 'kyb_edit' | 'kyb_submit' | 'documents_read' | 'documents_manage' | 'messages_read' | 'messages_send' | 'agreements_read' | 'agreements_sign' | 'audit_read' | 'members_read' | 'members_invite' | 'roles_manage' | 'networks_manage' | 'signers_manage' | 'api_keys_manage', required
      - `group` string, required
    - `performing` MembersroleAssignmentAtom[], required
      - `atom` 'payments_read' | 'payees_read' | 'payee_details_read' | 'investments_read' | 'automations_read' | 'reports_read' | 'statements_generate' | 'funds_deposit' | 'funds_withdraw' | 'assets_buy' | 'assets_sell' | 'bank_account_add' | 'bank_account_remove' | 'wallet_add' | 'automations_manage' | 'transfers_approve' | 'approval_controls_manage' | 'integrations_manage' | 'kyb_read' | 'kyb_edit' | 'kyb_submit' | 'documents_read' | 'documents_manage' | 'messages_read' | 'messages_send' | 'agreements_read' | 'agreements_sign' | 'audit_read' | 'members_read' | 'members_invite' | 'roles_manage' | 'networks_manage' | 'signers_manage' | 'api_keys_manage', required
      - `group` string, required
  - `proposed_role` AccessRole, nullable, required
    - `id` string, required: A preset's name, such as admin, or a custom role's id.
    - `kind` 'preset' | 'custom', required
    - `name` string, required: The role's name as members read it.
    - `revision` integer, required: The role revision whose capabilities apply.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `default`: Error response.

## Changes

- **2026-11-19** `aa2e3c3161d7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/stablesea/apis/stable-sea-backend/changes/identity/members/:id/role_previews/get.md)

---

[API](https://skmtc.dev/stablesea/apis/stable-sea-backend.md) - [All operations](https://skmtc.dev/stablesea/apis/stable-sea-backend/llms.txt) - [OpenAPI document](https://skmtc.dev/stablesea/apis/stable-sea-backend/revisions/f240ce7a9650?raw)
