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:

``bash
npm install @itwin/access-control-client
`

`typescript
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

`bash

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

$3

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

$3

Configure different deployment environments using globalThis.IMJS_URL_PREFIX:

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

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

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

Documentation

$3

| 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

$3

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

$3

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

$3

- ✅ 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

$3

`typescript
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: "user@example.com",
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

$3

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

$3

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

$3

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

`bash

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

$3

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.

---