RoleHandle
@iota/audit-trails API documentation
Class: RoleHandle
Role-scoped access-control API.
Remarks
Identifies one role name inside the trail's access-control state and builds transactions that act on that role.
Properties
name
readonlyname:string
Returns the role name represented by this handle.
Returns
The role name bound to this handle.
Methods
toJSON()
toJSON():
Object
- Return copy of self without private attributes.
Returns
Object
toString()
toString():
string
Return stringified version of self.
Returns
string
create()
create(
permissions,role_tags?):TransactionBuilder<CreateRole>
Builds a role-creation transaction.
Parameters
permissions
PermissionSet granted by the new role.
role_tags?
RoleTags | null
Returns
TransactionBuilder<CreateRole>
A TransactionBuilder wrapping the CreateRole transaction.
Remarks
Creates this role with permissions and the optional roleTags allowlist. Each tag
referenced by roleTags must already exist in the trail-owned tag registry; the on-chain
call aborts otherwise and bumps that tag's usage counter on success.
Requires the Permission.AddRoles permission.
Throws
When the wrapper was created from a read-only client.
Emits a RoleCreated event on success.
delete()
delete():
TransactionBuilder<DeleteRole>
Builds a role-deletion transaction for this role.
Returns
TransactionBuilder<DeleteRole>
A TransactionBuilder wrapping the DeleteRole transaction.
Remarks
Decrements the usage count of every tag the role's roleTags referenced. The reserved
initial-admin role cannot be deleted.
Requires the Permission.DeleteRoles permission.
Throws
When the wrapper was created from a read-only client.
Emits a RoleDeleted event on success.
issueCapability()
issueCapability(
options):TransactionBuilder<IssueCapability>
Builds a capability-issuance transaction for this role.
Parameters
options
CapabilityIssueOptions configuring recipient and validity window.
Returns
TransactionBuilder<IssueCapability>
A TransactionBuilder wrapping the IssueCapability transaction.
Remarks
The resulting capability always targets this trail and grants exactly this role. Only
options.issuedTo, options.validFromMs, and options.validUntilMs configure restrictions
on the issued object; enforcement happens on-chain when the capability is later presented
for authorization. The capability is transferred to options.issuedTo if set, otherwise to
the caller.
Requires the Permission.AddCapabilities permission.
Throws
When the wrapper was created from a read-only client.
Emits a CapabilityIssued event on success.
updatePermissions()
updatePermissions(
permissions,role_tags?):TransactionBuilder<UpdateRole>
Builds a role-update transaction for this role.
Parameters
permissions
Replacement PermissionSet for the role.
role_tags?
RoleTags | null
Returns
TransactionBuilder<UpdateRole>
A TransactionBuilder wrapping the UpdateRole transaction.
Remarks
Replaces both the role's permission set and its roleTags allowlist. Any newly supplied tag
must already exist in the trail's record-tag registry; tag usage counters are adjusted to
reflect the difference between the old and the new role-tag sets. Updating the
initial-admin role with permissions that do not include every permission configured in the
trail's role- and capability-admin permission sets aborts on-chain.
Requires the Permission.UpdateRoles permission.
Throws
When the wrapper was created from a read-only client.
Emits a RoleUpdated event on success.