User & Access Management
This section details the GraphQL mutations available for managing users, roles, permissions, invitations, and access keys within your ABT Node instance. These operations allow you to programmatically control access and modify user-related data. For read-only operations, please see the User & Access Management Queries.
User Management#
Mutations for creating, updating, and removing users and their associated data.
removeUser#
Permanently removes a user from the team or blocklet.
SDK Example
const { user } = await client.removeUser({
input: {
teamDid: 'z2qa...',
user: {
did: 'z82...'
}
}
});
console.log('User removed:', user.did);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team (or blocklet) from which the user will be removed. |
|
| The DID of the user to be removed. |
Example Response
{
"removeUser": {
"code": "ok",
"user": {
"did": "z82...",
"fullName": "John Doe",
"email": "john.doe@example.com"
}
}
}
updateUserTags#
Updates the tags associated with a specific user.
SDK Example
const { user } = await client.updateUserTags({
input: {
teamDid: 'z2qa...',
did: 'z82...',
tags: [1, 5]
}
});
console.log('User tags updated:', user.tags);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The DID of the user to update. |
|
| An array of tag IDs to associate with the user. This will replace any existing tags. |
Example Response
{
"updateUserTags": {
"code": "ok",
"user": {
"did": "z82...",
"tags": [
{ "id": 1, "title": "Developer" },
{ "id": 5, "title": "VIP" }
]
}
}
}
updateUserExtra#
Updates the remark
and extra
(a flexible JSON field) for a user.
SDK Example
const { user } = await client.updateUserExtra({
input: {
teamDid: 'z2qa...',
did: 'z82...',
remark: 'Valued customer since 2023',
extra: JSON.stringify({ company: 'ArcBlock' })
}
});
console.log('User extra data updated');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The DID of the user to update. |
|
| A new remark for the user. |
|
| A JSON string containing custom data to store. |
Example Response
{
"updateUserExtra": {
"code": "ok",
"user": {
"did": "z82...",
"remark": "Valued customer since 2023",
"extra": {
"company": "ArcBlock"
}
}
}
}
updateUserApproval#
Approves or revokes a user's access.
SDK Example
const { user } = await client.updateUserApproval({
input: {
teamDid: 'z2qa...',
user: {
did: 'z82...',
approved: true
}
}
});
console.log('User approval status:', user.approved);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The DID of the user whose approval status is being changed. |
|
| Set to |
Example Response
{
"updateUserApproval": {
"code": "ok",
"user": {
"did": "z82...",
"approved": true
}
}
}
updateUserInfo#
Updates a user's basic profile information.
SDK Example
const { user } = await client.updateUserInfo({
input: {
teamDid: 'z2qa...',
user: {
did: 'z82...',
fullName: 'Johnathan Doe',
email: 'johnathan.doe@example.com'
}
}
});
console.log('User info updated');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| An object containing the user's DID and the fields to update (e.g., |
Example Response
{
"updateUserInfo": {
"code": "ok",
"user": {
"did": "z82...",
"fullName": "Johnathan Doe",
"email": "johnathan.doe@example.com"
}
}
}
updateUserAddress#
Updates the physical address information for a user.
SDK Example
const { user } = await client.updateUserAddress({
input: {
teamDid: 'z2qa...',
did: 'z82...',
address: {
country: 'USA',
city: 'Bellevue',
line1: '1234 Main St'
}
}
});
console.log('User address updated');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The DID of the user to update. |
|
| An object containing the address details. |
Example Response
{
"updateUserAddress": {
"code": "ok",
"user": {
"did": "z82...",
"address": {
"country": "USA",
"city": "Bellevue",
"line1": "1234 Main St"
}
}
}
}
switchProfile#
Switches the user's current profile to a different one, effectively changing their active identity within the scope of the application.
SDK Example
const { user } = await client.switchProfile({
input: {
teamDid: 'z2qa...',
userDid: 'z82...',
profile: {
did: 'z3s...',
fullName: 'John Doe (Work)',
avatar: 'https://example.com/work-avatar.png'
}
}
});
console.log('User profile switched');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The current DID of the user. |
|
| An object containing the new profile information to switch to. |
Example Response
{
"switchProfile": {
"code": "ok",
"user": {
"did": "z3s...",
"fullName": "John Doe (Work)"
}
}
}
Passport Management#
Mutations for managing user passports and trusted issuers.
issuePassportToUser#
Issues a new passport to a user, assigning them a role.
SDK Example
const { user } = await client.issuePassportToUser({
input: {
teamDid: 'z2qa...',
userDid: 'z82...',
role: 'member',
display: {
type: 'text',
content: 'Member Passport'
}
}
});
console.log('Passport issued to user:', user.did);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet issuing the passport. |
|
| The DID of the user receiving the passport. |
|
| The role to assign to the user (e.g., 'guest', 'member', 'admin'). |
|
| Defines how the passport is displayed. |
|
| (Optional) Whether to send a notification to the user. |
|
| (Optional) Custom notification content as a JSON string. |
Example Response
{
"issuePassportToUser": {
"code": "ok",
"user": {
"did": "z82...",
"passports": [
{
"id": "...",
"role": "member"
}
]
}
}
}
revokeUserPassport#
Revokes a specific passport from a user.
SDK Example
const { user } = await client.revokeUserPassport({
input: {
teamDid: 'z2qa...',
userDid: 'z82...',
passportId: 'z3t...'
}
});
console.log('User passport revoked');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The DID of the user. |
|
| The ID of the passport to revoke. |
Example Response
{
"revokeUserPassport": {
"code": "ok",
"user": {
"did": "z82..."
}
}
}
enableUserPassport#
Re-enables a previously revoked passport for a user.
SDK Example
const { user } = await client.enableUserPassport({
input: {
teamDid: 'z2qa...',
userDid: 'z82...',
passportId: 'z3t...'
}
});
console.log('User passport enabled');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The DID of the user. |
|
| The ID of the passport to enable. |
Example Response
{
"enableUserPassport": {
"code": "ok",
"user": {
"did": "z82..."
}
}
}
removeUserPassport#
Permanently removes a passport from a user's profile.
SDK Example
await client.removeUserPassport({
input: {
teamDid: 'z2qa...',
userDid: 'z82...',
passportId: 'z3t...'
}
});
console.log('User passport removed');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The DID of the user. |
|
| The ID of the passport to remove. |
Example Response
{
"removeUserPassport": {
"code": "ok"
}
}
createPassportIssuance#
Creates a new passport issuance configuration.
SDK Example
const { info } = await client.createPassportIssuance({
input: {
teamDid: 'z2qa...',
name: 'Community Contributor',
display: {
type: 'text',
content: 'Community Contributor Badge'
}
}
});
console.log('Passport issuance created:', info.id);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The name of the passport issuance. |
|
| Defines how the passport is displayed. |
|
| (Optional) The expiration time for the issued passports. |
Example Response
{
"createPassportIssuance": {
"code": "ok",
"info": {
"id": "...",
"name": "Community Contributor"
}
}
}
deletePassportIssuance#
Deletes a passport issuance configuration.
SDK Example
await client.deletePassportIssuance({
input: {
teamDid: 'z2qa...',
sessionId: 'z3s...'
}
});
console.log('Passport issuance deleted');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The issuance ID to be deleted. |
Example Response
{
"deletePassportIssuance": {
"code": "ok"
}
}
configTrustedPassports#
Configures the list of trusted passport issuers for a team or blocklet.
SDK Example
await client.configTrustedPassports({
input: {
teamDid: 'z2qa...',
trustedPassports: [
{
issuerDid: 'zNK...',
remark: 'Main Identity Provider',
mappings: [
{
from: { passport: 'gold_member' },
to: { role: 'admin' }
}
]
}
]
}
});
console.log('Trusted passports configured.');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| An array of trusted passport configurations. This will overwrite the existing list. |
Example Response
{
"configTrustedPassports": {
"code": "ok"
}
}
configTrustedFactories#
Configures trusted factories for issuing passports.
SDK Example
await client.configTrustedFactories({
input: {
teamDid: 'z2qa...',
trustedFactories: [
{
factoryAddress: '0x...',
issuerDid: 'zNK...',
passport: {
role: 'member'
}
}
]
}
});
console.log('Trusted factories configured');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| An array of trusted factory configurations. |
Example Response
{
"configTrustedFactories": {
"code": "ok"
}
}
configPassportIssuance#
Enables or disables passport issuance for a team or blocklet.
SDK Example
await client.configPassportIssuance({
input: {
teamDid: 'z2qa...',
enable: true
}
});
console.log('Passport issuance enabled');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| Set to |
Example Response
{
"configPassportIssuance": {
"code": "ok"
}
}
Role & Permission Management#
Mutations for managing roles and their associated permissions.
createRole#
Creates a new role with a specified set of permissions.
SDK Example
const { role } = await client.createRole({
input: {
teamDid: 'z2qa...',
name: 'editor',
title: 'Editor',
description: 'Can edit content but not publish.',
permissions: ['content:edit']
}
});
console.log('Role created:', role.name);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| A unique name for the role (e.g., 'editor'). |
|
| A human-readable title for the role (e.g., 'Editor'). |
|
| A description of the role's purpose. |
|
| An array of permission names to grant to this role initially. |
Example Response
{
"createRole": {
"code": "ok",
"role": {
"name": "editor",
"title": "Editor",
"grants": ["content:edit"]
}
}
}
updateRole#
Updates the details of an existing role.
SDK Example
const { role } = await client.updateRole({
input: {
teamDid: 'z2qa...',
role: {
name: 'editor',
title: 'Content Editor',
description: 'Can create and edit content.'
}
}
});
console.log('Role updated:', role.name);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The name of the role to update. |
|
| The new title for the role. |
|
| The new description for the role. |
Example Response
{
"updateRole": {
"code": "ok",
"role": {
"name": "editor",
"title": "Content Editor"
}
}
}
deleteRole#
Deletes a role. This action cannot be undone.
SDK Example
await client.deleteRole({
input: {
teamDid: 'z2qa...',
name: 'editor'
}
});
console.log('Role editor deleted.');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The name of the role to delete. |
Example Response
{
"deleteRole": {
"code": "ok"
}
}
createPermission#
Creates a new permission.
SDK Example
const { permission } = await client.createPermission({
input: {
teamDid: 'z2qa...',
name: 'content:publish',
description: 'Allows publishing content'
}
});
console.log('Permission created:', permission.name);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The name of the permission (e.g., 'content:publish'). |
|
| A description of what the permission allows. |
Example Response
{
"createPermission": {
"code": "ok",
"permission": {
"name": "content:publish",
"description": "Allows publishing content"
}
}
}
updatePermission#
Updates an existing permission's description.
SDK Example
const { permission } = await client.updatePermission({
input: {
teamDid: 'z2qa...',
permission: {
name: 'content:publish',
description: 'Allows publishing and unpublishing content'
}
}
});
console.log('Permission updated:', permission.description);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The name of the permission to update. |
|
| The new description for the permission. |
Example Response
{
"updatePermission": {
"code": "ok",
"permission": {
"name": "content:publish",
"description": "Allows publishing and unpublishing content"
}
}
}
deletePermission#
Deletes a permission. This action cannot be undone.
SDK Example
await client.deletePermission({
input: {
teamDid: 'z2qa...',
name: 'content:publish'
}
});
console.log('Permission deleted.');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The name of the permission to delete. |
Example Response
{
"deletePermission": {
"code": "ok"
}
}
grantPermissionForRole#
Grants a specific permission to a role.
SDK Example
await client.grantPermissionForRole({
input: {
teamDid: 'z2qa...',
roleName: 'editor',
grantName: 'content:publish'
}
});
console.log('Permission granted.');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The name of the role. |
|
| The name of the permission to grant. |
Example Response
{
"grantPermissionForRole": {
"code": "ok"
}
}
revokePermissionFromRole#
Revokes a specific permission from a role.
SDK Example
await client.revokePermissionFromRole({
input: {
teamDid: 'z2qa...',
roleName: 'editor',
grantName: 'content:publish'
}
});
console.log('Permission revoked.');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The name of the role. |
|
| The name of the permission to revoke. |
Example Response
{
"revokePermissionFromRole": {
"code": "ok"
}
}
updatePermissionsForRole#
Sets the complete list of permissions for a role, overwriting any existing permissions.
SDK Example
const { role } = await client.updatePermissionsForRole({
input: {
teamDid: 'z2qa...',
roleName: 'editor',
grantNames: ['content:edit', 'content:create']
}
});
console.log('Permissions for role updated:', role.grants);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The name of the role to update. |
|
| An array of permission names to set for the role. |
Example Response
{
"updatePermissionsForRole": {
"code": "ok",
"role": {
"name": "editor",
"grants": ["content:edit", "content:create"]
}
}
}
Invitation Management#
Mutations for creating and managing user invitations.
createMemberInvitation#
Creates an invitation for a new member to join with a specific role.
SDK Example
const { inviteInfo } = await client.createMemberInvitation({
input: {
teamDid: 'z2qa...',
role: 'member',
remark: 'Invitation for new developer'
}
});
console.log('Invitation created:', inviteInfo.inviteId);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The role to assign to the invited user. |
|
| A remark or note for the invitation. |
Example Response
{
"createMemberInvitation": {
"code": "ok",
"inviteInfo": {
"inviteId": "...",
"role": "member"
}
}
}
createTransferInvitation#
Creates a special invitation to transfer ownership of the node.
SDK Example
const { inviteInfo } = await client.createTransferInvitation({
input: {
teamDid: 'z2qa...',
remark: 'Transferring node ownership'
}
});
console.log('Transfer invitation created:', inviteInfo.inviteId);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| A remark for the transfer invitation. |
Example Response
{
"createTransferInvitation": {
"code": "ok",
"inviteInfo": {
"inviteId": "...",
"role": "owner"
}
}
}
deleteInvitation#
Deletes an existing invitation.
SDK Example
await client.deleteInvitation({
input: {
teamDid: 'z2qa...',
inviteId: 'ziv_...'
}
});
console.log('Invitation deleted');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The ID of the invitation to delete. |
Example Response
{
"deleteInvitation": {
"code": "ok"
}
}
Access Key Management#
Mutations for creating and managing programmatic access keys.
createAccessKey#
Creates a new access key for programmatic access.
SDK Example
const { data } = await client.createAccessKey({
input: {
teamDid: 'z2qa...',
remark: 'CI/CD Pipeline Key',
authType: 'app'
}
});
console.log('Access Key Created:', data.accessKeyId, data.accessKeySecret);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| A description for the access key. |
|
| The authentication type, typically 'app'. |
Example Response
{
"createAccessKey": {
"code": "ok",
"data": {
"accessKeyId": "zKey...",
"accessKeySecret": "...",
"remark": "CI/CD Pipeline Key"
}
}
}
updateAccessKey#
Updates the remark of an existing access key.
SDK Example
const { data } = await client.updateAccessKey({
input: {
teamDid: 'z2qa...',
accessKeyId: 'zKey...',
remark: 'CI/CD Pipeline Key (Updated)'
}
});
console.log('Access key updated:', data.remark);
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The ID of the access key to update. |
|
| The new remark for the access key. |
Example Response
{
"updateAccessKey": {
"code": "ok",
"data": {
"accessKeyId": "zKey...",
"remark": "CI/CD Pipeline Key (Updated)"
}
}
}
deleteAccessKey#
Deletes an access key, revoking its access.
SDK Example
await client.deleteAccessKey({
input: {
teamDid: 'z2qa...',
accessKeyId: 'zKey...'
}
});
console.log('Access key deleted.');
Parameters
Parameter | Type | Description |
---|---|---|
|
| The DID of the team or blocklet. |
|
| The ID of the access key to delete. |
Example Response
{
"deleteAccessKey": {
"code": "ok"
}
}
With these mutations, you can build comprehensive user and access control systems for your applications. Next, explore mutations for managing Networking & Services.