API Reference
User & Access Management

This section provides a detailed reference for GraphQL queries used to retrieve information about users, roles, permissions, sessions, and access keys. These queries are essential for building applications that require robust user management and access control. For operations that modify this data, such as creating a user or updating a role, please refer to the User & Access Management Mutations documentation.
In This Section#Users: Fetch user lists and individual user details.
Roles & Permissions: Retrieve role definitions and their associated permissions.
Sessions: Get information about active user sessions.
Access Keys: List and retrieve programmatic access keys.
Invitations & Passports: Query user invitations, passport issuances, and related data.
Social Features: Fetch user follow/follower relationships and statistics.
Tags: Retrieve user tags for organization.

Users#Queries for fetching user information.
getUsers#Retrieves a paginated list of users.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application to query users from.
input.paging
PagingInput
Pagination options for the list.
input.query
UserQueryInput
Filters for the user list, such as by role, approval status, or search term.
input.sort
UserSortInput
Sorting options for the list, such as by creation date or last login.
input.dids
string[]
An array of user DIDs to fetch specifically.
Example
const client = new BlockletServerClient();
const { users, paging } = await client.getUsers({
  input: {
    teamDid: 'zde...', // The application's DID
    query: { role: 'guest' },
    paging: { page: 1, pageSize: 10 },
    sort: { lastLoginAt: -1 } // Sort by most recent login
  }
});
console.log('Users:', users);
console.log('Paging Info:', paging);Response Example
{
  "getUsers": {
    "code": "ok",
    "users": [
      {
        "did": "z8ia...",
        "fullName": "John Doe",
        "email": "john.doe@example.com",
        "role": "guest",
        "approved": true,
        "lastLoginAt": 1678886400
      }
    ],
    "paging": {
      "total": 1,
      "pageSize": 10,
      "page": 1
    }
  }
}getUser#Retrieves detailed information for a single user by their DID.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.user.did
string
The DID of the user to retrieve.
input.options
RequestTeamUserOptionsInput
Options to include additional data like connectedAccounts or tags.
Example
const client = new BlockletServerClient();
const { user } = await client.getUser({
  input: {
    teamDid: 'zde...', // The application's DID
    user: { did: 'z8ia...' },
    options: { includeTags: true }
  }
});
console.log('User Details:', user);Response Example
{
  "getUser": {
    "code": "ok",
    "user": {
      "did": "z8ia...",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "role": "guest",
      "approved": true,
      "tags": [
        {
          "id": 1,
          "title": "VIP"
        }
      ]
    }
  }
}getUsersCount#Retrieves the total number of users for a team.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
Example
const client = new BlockletServerClient();
const { count } = await client.getUsersCount({
  input: { teamDid: 'zde...' }
});
console.log('Total users:', count);Response Example
{
  "getUsersCount": {
    "code": "ok",
    "count": 150
  }
}getUsersCountPerRole#Retrieves the count of users for each role within a team.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
Example
const client = new BlockletServerClient();
const { counts } = await client.getUsersCountPerRole({
  input: { teamDid: 'zde...' }
});
console.log('User counts by role:', counts);Response Example
{
  "getUsersCountPerRole": {
    "code": "ok",
    "counts": [
      { "key": "owner", "value": 1 },
      { "key": "admin", "value": 5 },
      { "key": "member", "value": 42 },
      { "key": "guest", "value": 102 }
    ]
  }
}getOwner#Retrieves the owner of the application or team.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
Example
const client = new BlockletServerClient();
const { user } = await client.getOwner({ input: { teamDid: 'zde...' } });
console.log('Owner:', user.fullName);Response Example
{
  "getOwner": {
    "code": "ok",
    "user": {
      "did": "zNK...",
      "fullName": "Alice",
      "role": "owner"
    }
  }
}
Roles & Permissions#Queries for managing roles and permissions.
getRoles#Retrieves a list of all roles defined for a team.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
Example
const client = new BlockletServerClient();
const { roles } = await client.getRoles({ input: { teamDid: 'zde...' } });
console.log('Available Roles:', roles.map(r => r.name));Response Example
{
  "getRoles": {
    "code": "ok",
    "roles": [
      {
        "name": "admin",
        "title": "Administrator",
        "description": "Has full access to all features.",
        "grants": ["*"]
      },
      {
        "name": "member",
        "title": "Member",
        "description": "Can access standard features.",
        "grants": ["read:posts", "write:posts"]
      }
    ]
  }
}getRole#Retrieves details for a specific role.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.role.name
string
The name of the role to retrieve.
Example
const client = new BlockletServerClient();
const { role } = await client.getRole({ input: { teamDid: 'zde...', role: { name: 'member' } } });
console.log('Role Details:', role);Response Example
{
  "getRole": {
    "code": "ok",
    "role": {
      "name": "member",
      "title": "Member",
      "description": "Can access standard features.",
      "grants": ["read:posts", "write:posts"]
    }
  }
}getPermissions#Retrieves a list of all available permissions for a team.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
Example
const client = new BlockletServerClient();
const { permissions } = await client.getPermissions({ input: { teamDid: 'zde...' } });
console.log('Available Permissions:', permissions);Response Example
{
  "getPermissions": {
    "code": "ok",
    "permissions": [
      {
        "name": "read:posts",
        "description": "Allows reading posts."
      },
      {
        "name": "write:posts",
        "description": "Allows creating and editing posts."
      }
    ]
  }
}getPermissionsByRole#Retrieves the permissions granted to a specific role.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.role.name
string
The name of the role.
Example
const client = new BlockletServerClient();
const { permissions } = await client.getPermissionsByRole({ input: { teamDid: 'zde...', role: { name: 'member' } } });
console.log('Permissions for member role:', permissions);Response Example
{
  "getPermissionsByRole": {
    "code": "ok",
    "permissions": [
      {
        "name": "read:posts",
        "description": "Allows reading posts."
      },
      {
        "name": "write:posts",
        "description": "Allows creating and editing posts."
      }
    ]
  }
}
Sessions#Queries for managing user sessions.
getUserSessions#Retrieves a list of active sessions for a user.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.query.userDid
string
The DID of the user whose sessions are to be fetched.
input.paging
PagingInput
Pagination options.
Example
const client = new BlockletServerClient();
const { list } = await client.getUserSessions({
  input: {
    teamDid: 'zde...',
    query: { userDid: 'z8ia...' },
    paging: { pageSize: 5 }
  }
});
console.log('User Sessions:', list);Response Example
{
  "getUserSessions": {
    "code": "ok",
    "list": [
      {
        "id": "...",
        "visitorId": "...",
        "ua": "Mozilla/5.0 ...",
        "lastLoginIp": "192.168.1.1",
        "createdAt": 1678886400
      }
    ]
  }
}getUserSessionsCount#Retrieves the count of sessions for a user.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.query.userDid
string
The DID of the user.
Example
const client = new BlockletServerClient();
const { count } = await client.getUserSessionsCount({
  input: {
    teamDid: 'zde...',
    query: { userDid: 'z8ia...' }
  }
});
console.log('Active session count:', count);Response Example
{
  "getUserSessionsCount": {
    "code": "ok",
    "count": 2
  }
}getSession#Retrieves a single session by its ID.
Parameters
Field
Type
Description
input.id
string
The unique identifier of the session.
Example
const client = new BlockletServerClient();
const { session } = await client.getSession({ input: { id: 'z123...' } });
console.log('Session details:', session);Response Example
{
  "getSession": {
    "code": "ok",
    "session": {
      "id": "z123...",
      "visitorId": "v456...",
      "userDid": "z8ia...",
      "status": "active",
      "createdAt": 1678886400
    }
  }
}
Access Keys#Queries for managing programmatic access keys.
getAccessKeys#Retrieves a list of access keys for a team.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.paging
PagingInput
Pagination options.
Example
const client = new BlockletServerClient();
const { list } = await client.getAccessKeys({ input: { teamDid: 'zde...' } });
console.log('Access Keys:', list);Response Example
{
  "getAccessKeys": {
    "code": "ok",
    "list": [
      {
        "accessKeyId": "...",
        "remark": "CI/CD Key",
        "createdAt": 1678886400,
        "lastUsedAt": 1678890000
      }
    ]
  }
}getAccessKey#Retrieves details for a single access key.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.accessKeyId
string
The ID of the access key to retrieve.
Example
const client = new BlockletServerClient();
const { data } = await client.getAccessKey({ input: { teamDid: 'zde...', accessKeyId: '...' } });
console.log('Access Key Details:', data);Response Example
{
  "getAccessKey": {
    "code": "ok",
    "data": {
      "accessKeyId": "...",
      "accessKeyPublic": "...",
      "remark": "CI/CD Key",
      "createdAt": 1678886400
    }
  }
}
Invitations & Passports#Queries related to user invitations and DID Passports.
getInvitations#Retrieves a list of pending invitations for a team.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
Example
const client = new BlockletServerClient();
const { invitations } = await client.getInvitations({ input: { teamDid: 'zde...' } });
console.log('Pending Invitations:', invitations);Response Example
{
  "getInvitations": {
    "code": "ok",
    "invitations": [
      {
        "inviteId": "...",
        "role": "member",
        "remark": "Project Alpha Team",
        "expireDate": "2023-12-31T23:59:59Z"
      }
    ]
  }
}getPassportIssuances#Retrieves passport issuance configurations.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.ownerDid
string
Optional. Filter issuances by the owner's DID.
Example
const client = new BlockletServerClient();
const { list } = await client.getPassportIssuances({ input: { teamDid: 'zde...' } });
console.log('Passport Issuances:', list);Response Example
{
  "getPassportIssuances": {
    "code": "ok",
    "list": [
      {
        "id": "...",
        "name": "Team Member Passport",
        "title": "Team Member",
        "expireDate": "365d"
      }
    ]
  }
}getPassportsByRole#Retrieves passports filtered by a specific role.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.query.role
string
The role to filter passports by (e.g., 'admin', 'member').
input.paging
PagingInput
Pagination options.
Example
const client = new BlockletServerClient();
const { passports } = await client.getPassportsByRole({ 
  input: { 
    teamDid: 'zde...', 
    query: { role: 'admin' },
    paging: { pageSize: 20 }
  } 
});
console.log('Admin Passports:', passports);Response Example
{
  "getPassportsByRole": {
    "code": "ok",
    "passports": [
      {
        "id": "...",
        "name": "Admin Passport",
        "userDid": "z8ia...",
        "status": "active"
      }
    ]
  }
}getPassportLogs#Retrieves activity logs for a specific passport.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.query.passportId
string
The ID of the passport to retrieve logs for.
input.paging
PagingInput
Pagination options.
Example
const client = new BlockletServerClient();
const { passportLogs } = await client.getPassportLogs({ 
  input: { 
    teamDid: 'zde...', 
    query: { passportId: '...' },
    paging: { pageSize: 10 }
  } 
});
console.log('Passport Logs:', passportLogs);Response Example
{
  "getPassportLogs": {
    "passportLogs": [
      {
        "id": 123,
        "passportId": "...",
        "action": "login",
        "operatorIp": "192.168.1.1",
        "createdAt": 1678886400
      }
    ],
    "paging": {
      "total": 1,
      "pageSize": 10,
      "page": 1
    }
  }
}getRelatedPassports#Retrieves passports that are related to a given passport, typically meaning other passports held by the same user.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.passportId
string
The ID of the passport to find relations for.
input.paging
PagingInput
Pagination options.
Example
const client = new BlockletServerClient();
const { passports } = await client.getRelatedPassports({ 
  input: { 
    teamDid: 'zde...', 
    passportId: '...',
    paging: { pageSize: 5 }
  } 
});
console.log('Related Passports:', passports);Response Example
{
  "getRelatedPassports": {
    "code": "ok",
    "passports": [
      {
        "id": "...",
        "name": "Another Passport",
        "userDid": "z8ia...",
        "status": "active"
      }
    ]
  }
}getPassportRoleCounts#Retrieves the count of passports for each role within a team.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
Example
const client = new BlockletServerClient();
const { counts } = await client.getPassportRoleCounts({ input: { teamDid: 'zde...' } });
console.log('Passport counts by role:', counts);Response Example
{
  "getPassportRoleCounts": {
    "code": "ok",
    "counts": [
      { "key": "admin", "value": 10 },
      { "key": "member", "value": 50 }
    ]
  }
}
Social Features#Queries related to social interactions between users.
getUserFollowers#Retrieves a list of users who are following a specified user.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.userDid
string
The DID of the user to get followers for.
input.paging
PagingInput
Pagination options.
Example
const client = new BlockletServerClient();
const { data } = await client.getUserFollowers({ 
  input: { 
    teamDid: 'zde...', 
    userDid: 'z8ia...', 
    paging: { pageSize: 10 } 
  } 
});
console.log('Followers:', data);getUserFollowing#Retrieves a list of users that a specified user is following.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.userDid
string
The DID of the user to get following list for.
input.paging
PagingInput
Pagination options.
Example
const client = new BlockletServerClient();
const { data } = await client.getUserFollowing({ 
  input: { 
    teamDid: 'zde...', 
    userDid: 'z8ia...', 
    paging: { pageSize: 10 } 
  } 
});
console.log('Following:', data);getUserFollowStats#Retrieves the follower and following counts for one or more users.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.userDids
string[]
An array of user DIDs to get stats for.
Example
const client = new BlockletServerClient();
const { data } = await client.getUserFollowStats({ 
  input: { 
    teamDid: 'zde...', 
    userDids: ['z8ia...', 'z2jb...'] 
  } 
});
console.log('Follow Stats:', data);checkFollowing#Checks if a user is following one or more other users.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.followerDid
string
The DID of the user who is potentially following others.
input.userDids
string[]
An array of user DIDs to check if they are being followed.
Example
const client = new BlockletServerClient();
const { data } = await client.checkFollowing({ 
  input: { 
    teamDid: 'zde...', 
    followerDid: 'z1ab...', 
    userDids: ['z8ia...', 'z2jb...'] 
  } 
});
// data will be an object like: { 'z8ia...': true, 'z2jb...': false }
console.log('Following Status:', data);
Tags#Queries for managing user tags.
getTags#Retrieves a paginated list of user tags for a team.
Parameters
Field
Type
Description
input.teamDid
string
The DID of the team/application.
input.paging
PagingInput
Pagination options.
Example
const client = new BlockletServerClient();
const { tags, paging } = await client.getTags({
  input: {
    teamDid: 'zde...',
    paging: { page: 1, pageSize: 20 }
  }
});
console.log('User Tags:', tags);Response Example
{
  "getTags": {
    "code": "ok",
    "tags": [
      {
        "id": 1,
        "title": "VIP",
        "description": "VIP users",
        "color": "#FFD700"
      }
    ],
    "paging": {
      "total": 1,
      "pageSize": 20,
      "page": 1
    }
  }
}
Next Steps#After reviewing these queries, you may want to explore how to manage network settings and services.
Next: Networking & Services Queries
Field	Type	Description
`input.teamDid`	`string`	The DID of the team/application to query users from.
`input.paging`	`PagingInput`	Pagination options for the list.
`input.query`	`UserQueryInput`	Filters for the user list, such as by role, approval status, or search term.
`input.sort`	`UserSortInput`	Sorting options for the list, such as by creation date or last login.
`input.dids`	`string[]`	An array of user DIDs to fetch specifically.
Field	Type	Description
`input.teamDid`	`string`	The DID of the team/application.
`input.user.did`	`string`	The DID of the user to retrieve.
`input.options`	`RequestTeamUserOptionsInput`	Options to include additional data like `connectedAccounts` or `tags`.
Overview

Getting Started

Authentication

API Reference

Advanced Usage

User & Access Management

In This Section#

Users#

getUsers#

getUser#

getUsersCount#

getUsersCountPerRole#

getOwner#

Roles & Permissions#

getRoles#

getRole#

getPermissions#

getPermissionsByRole#

Sessions#

getUserSessions#

getUserSessionsCount#

getSession#

Access Keys#

getAccessKeys#

getAccessKey#

Invitations & Passports#

getInvitations#

getPassportIssuances#

getPassportsByRole#

getPassportLogs#

getRelatedPassports#

getPassportRoleCounts#

Social Features#

getUserFollowers#

getUserFollowing#

getUserFollowStats#

checkFollowing#

Tags#

getTags#

Next Steps#

Node & Blocklet Management

Networking & Services
