SCIM 2.0

Provision and manage users via the SCIM 2.0 protocol, and manage SCIM bearer tokens.

Overview

The scim sub-client implements SCIM 2.0 (System for Cross-domain Identity Management) for automated user provisioning. It also provides SCIM token management for authenticating identity providers.

// Create a SCIM token for your IdP
const token = await grantex.scim.createToken({ label: 'Okta Production' });
console.log(token.token); // Store securely -- shown only once

// Provision a user
const user = await grantex.scim.createUser({
  userName: '[e-mail]',
  displayName: 'Alice Smith',
  emails: [{ value: '[e-mail]', primary: true }],
});

---

Token Management

SCIM tokens authenticate your identity provider (e.g. Okta, Azure AD) when it calls the Grantex SCIM endpoints.

scim.createToken()

Create a new SCIM bearer token. The raw token value is returned only once.

const scimToken = await grantex.scim.createToken({
  label: 'Okta Production',
});

console.log(scimToken.id);        // 'scim_tok_01HXYZ...'
console.log(scimToken.label);     // 'Okta Production'
console.log(scimToken.token);     // 'scim_01HXYZ...' -- store securely!
console.log(scimToken.createdAt); // '2026-02-28T12:00:00Z'

Parameters

label · string · required

A human-readable label for the token (e.g. the IdP name).

Response: ScimTokenWithSecret

id · string

Unique token identifier.

label · string

The token label.

token · string

The raw bearer token. Only returned on creation.

createdAt · string

ISO 8601 creation timestamp.

lastUsedAt · string | null

ISO 8601 timestamp of last use, or null.

---

scim.listTokens()

List all SCIM tokens for your organization (without raw secrets).

const result = await grantex.scim.listTokens();

for (const token of result.tokens) {
  console.log(`${token.label} (${token.id}) - last used: ${token.lastUsedAt ?? 'never'}`);
}

Response: ListScimTokensResponse

tokens · ScimToken[]

Array of token objects (without the raw token field).

---

scim.revokeToken()

Revoke a SCIM token by its ID.

await grantex.scim.revokeToken('scim_tok_01HXYZ...');
// Returns void -- the token is now invalid

Parameters

id · string · required

The SCIM token ID to revoke.

Response

Returns void.

---

User Operations

These methods implement the SCIM 2.0 user provisioning protocol. They are typically called by your identity provider automatically, but can also be used directly.

scim.listUsers()

List provisioned users with pagination.

const result = await grantex.scim.listUsers({
  startIndex: 1,
  count: 25,
});

console.log(result.totalResults); // 100
console.log(result.startIndex);   // 1
console.log(result.itemsPerPage); // 25
for (const user of result.Resources) {
  console.log(`${user.userName} (${user.active ? 'active' : 'inactive'})`);
}

Parameters

startIndex · number

1-indexed start position for pagination.

count · number

Maximum number of users to return.

Response: ScimListResponse

totalResults · number

Total number of provisioned users.

startIndex · number

The start index of this page.

itemsPerPage · number

Number of users in this page.

Resources · ScimUser[]

Array of SCIM user objects.

---

scim.createUser()

Provision a new user.

const user = await grantex.scim.createUser({
  userName: '[e-mail]',
  displayName: 'Alice Smith',
  externalId: 'okta-12345',
  emails: [{ value: '[e-mail]', primary: true }],
  active: true,
});

console.log(user.id);       // 'scim_usr_01HXYZ...'
console.log(user.userName);  // '[e-mail]'

Parameters

userName · string · required

The user’s unique username (typically an email).

displayName · string

The user’s display name.

externalId · string

External ID from the identity provider.

emails · ScimEmail[]

Array of email objects: { value: string, primary?: boolean }.

active · boolean

Whether the user is active.

Response: ScimUser

id · string

Unique SCIM user identifier.

externalId · string

External ID from the identity provider.

userName · string

The user’s username.

displayName · string

The user’s display name.

active · boolean

Whether the user is active.

emails · ScimEmail[]

Array of email objects.

meta · ScimUserMeta

SCIM metadata: { resourceType, created, lastModified }.

---

scim.getUser()

Get a single provisioned user by ID.

const user = await grantex.scim.getUser('scim_usr_01HXYZ...');
console.log(user.userName);    // '[e-mail]'
console.log(user.displayName); // 'Alice Smith'

Parameters

id · string · required

The SCIM user ID.

Response

Returns a ScimUser object.

---

scim.replaceUser()

Full replace of a user (SCIM PUT operation).

const updated = await grantex.scim.replaceUser('scim_usr_01HXYZ...', {
  userName: '[e-mail]',
  displayName: 'Alice Johnson',
  emails: [{ value: '[e-mail]', primary: true }],
  active: true,
});

Parameters

id · string · required

The SCIM user ID to replace.

params · CreateScimUserParams · required

The complete user representation.

Response

Returns the updated ScimUser object.

---

scim.updateUser()

Partial update via SCIM Operations (SCIM PATCH operation).

const updated = await grantex.scim.updateUser('scim_usr_01HXYZ...', [
  { op: 'replace', path: 'displayName', value: 'Alice Johnson' },
  { op: 'replace', path: 'active', value: false },
]);

console.log(updated.displayName); // 'Alice Johnson'
console.log(updated.active);      // false

Parameters

id · string · required

The SCIM user ID to update.

operations · Array<{ op: string; path?: string; value: unknown }> · required

Array of SCIM patch operations. Supported op values: 'add', 'replace', 'remove'.

Response

Returns the updated ScimUser object.

---

scim.deleteUser()

Deprovision a user (SCIM DELETE operation).

await grantex.scim.deleteUser('scim_usr_01HXYZ...');
// Returns void -- the user is deprovisioned

Parameters

id · string · required

The SCIM user ID to delete.

Response

Returns void.