Skip to content

Change a member's access

Change an organization member's role and replace their granted and withheld commands. Choosing billing_owner offers billing ownership, which transfers when the member accepts.

Parameters

#
userstringRequired
The member whose access to change, by email address or user ID.
rolestring
New role, user, admin or billing_owner. Omit to keep the current role while replacing command permissions. An offer of billing_owner takes effect on acceptance and takes no grants or withholds.
grantsstring[]
Management command in the replacement list of additional permissions. Omit to clear extra grants.
withholdsstring[]
Management command in the replacement list of withheld permissions. Omit to clear withholding, subject to your own permissions.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
A saved role change, or an invitation offering billing ownership.
Show 2 attributesHide attributes
alternative-1object
The member's saved role or command grants.
Show 2 attributesHide attributes
grant_scopestring
Resources on which the additional command grants apply. May be omitted.
updatedbooleanAlways present
Whether the membership permissions were saved.
alternative-2object
An offer of billing ownership. The recipient must accept the invitation before the role transfers.
Show 2 attributesHide attributes
invite_idstringAlways present
Invitation used to accept the offer.
offeredstringAlways present
Billing ownership offered to the member.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • CLI: heaven login with HEAVEN_API_KEY unset. MCP: Heaven sign-in. cURL: HEAVEN_SIGN_IN_KEY from approved device sign-in (POST /v1/auth/create).
  • A key limited to a command list cannot run this command.