@itwin/access-control-client

Access Control Client Library

A comprehensive TypeScript library for Bentley Systems' Access Control API, providing type-safe access to iTwin access management, roles, permissions, groups, and member operations.

Table of Contents

• Quick Start
• Installation
• Basic Usage
• Documentation
• API Reference
• About this Repository
• Development
• Contributing
• License

Quick Start

Get up and running with Access Control Client in just a few steps:

npm install @itwin/access-control-client

import { AccessControlClient } from "@itwin/access-control-client";

const client = new AccessControlClient();
const accessToken = "your-access-token-string";
const roles = await client.roles.getITwinRoles(accessToken, "itwin-id");
console.log(`Found ${roles.data!.length} roles`);

Installation

# Using npm
npm install @itwin/access-control-client

# Using yarn
yarn add @itwin/access-control-client

# Using pnpm
pnpm add @itwin/access-control-client

Basic Usage

Authentication

All API methods require an access token string. See the iTwin Platform documentation for authentication setup.

Environment Configuration

Configure different deployment environments using globalThis.IMJS_URL_PREFIX:

// Development environment
globalThis.IMJS_URL_PREFIX = "dev-";

// QA environment
globalThis.IMJS_URL_PREFIX = "qa-";

// Production (default)
globalThis.IMJS_URL_PREFIX = undefined;

Documentation

Core Documentation

Document	Purpose
Getting Started Guide	Complete setup and first steps
Migration Guide v3→v4	Upgrading from v3.x to v4.x
Contributing Guide	Development and contribution workflow

API Reference

Core Classes

• AccessControlClient - Main client for all access control operations
• IAccessControlClient - Interface defining the client API surface

Sub-Clients

The AccessControlClient exposes the following specialized sub-clients:

Access Management

• permissions - Query permissions across the platform and iTwins
• roles - Manage iTwin roles (CRUD operations)

Group Management

• groups - Manage iTwin groups (CRUD operations)
• groupMembers - Manage members within groups
• groupMemberInvitations - Handle group member invitation lifecycle

User Management

• userMembers - Manage individual user members of iTwins
• ownerMembers - Manage iTwin owner memberships
• memberInvitations - Handle member invitation lifecycle

Advanced Operations

• itwinJobs - Bulk operations for member management
• itwinShares - Manage iTwin sharing and access tokens

Key Features

• ✅ Complete CRUD operations for roles, groups, and members
• ✅ Bulk operations via iTwin Jobs
• ✅ Invitation management for users and groups
• ✅ Sharing capabilities for controlled iTwin access
• ✅ Type-safe API with full TypeScript support

Quick Reference

import { AccessControlClient } from "@itwin/access-control-client";
import type {
  BentleyAPIResponse,
  Role,
  MultipleUserMembersResponse
} from "@itwin/access-control-client";

const client = new AccessControlClient();
const accessToken = "your-access-token-string";
const iTwinId = "your-itwin-id";

// Get roles
const roles = await client.roles.getITwinRoles(accessToken, iTwinId);

// Create a role
const newRole = await client.roles.createITwinRole(accessToken, iTwinId, {
  displayName: "Project Manager",
  description: "Role for project management"
});

// Query user members
const members = await client.userMembers.queryITwinUserMembers(
  accessToken,
  iTwinId,
  { top: 10 }
);

// Add user members
const addedMembers = await client.userMembers.addITwinUserMembers(
  accessToken,
  iTwinId,
  [{
    email: "[e-mail]",
    roleIds: ["role-id"]
  }],
  "Welcome message"
);

About this Repository

The @itwin/access-control-client package provides a modern, type-safe interface to Bentley Systems' Access Control API. It manages iTwin access permissions, roles, groups, members, invitations, and sharing capabilities.

For more information about the iTwin platform and APIs, visit:

• iTwin Developer Portal
• Access Control API Documentation
• iTwin.js Platform

Development

Prerequisites

• Node.js 16+ and pnpm
• TypeScript 4.5+
• Valid iTwin Platform credentials

Building from Source

git clone https://github.com/iTwin/access-control-client.git
cd access-control-client
pnpm install
pnpm build

Running Tests

.env file setup is required for tests. View Getting Started for more information.

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run linting
pnpm lint

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• How to submit issues and feature requests
• Development workflow and coding standards
• Pull request process and review guidelines
• Testing requirements and conventions
• How to use changesets for versioning

Versioning

This project uses Changesets for version management. For more information view Contributing Guide.

License

Copyright © Bentley Systems, Incorporated. All rights reserved.

This project is licensed under the MIT License - see the LICENSE.md file for details.