CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-gitbeaker--rest

Cross Platform implementation of the GitLab API

Overview
Eval results
Files

users.mddocs/

Users

User management capabilities including profile operations, SSH keys, GPG keys, emails, impersonation tokens, and user administration.

Capabilities

User Operations

List, create, show, edit, and manage users with administrative privileges.

/**
 * Users resource class for user management
 */
class Users<C extends boolean = false> {
  /**
   * List all users with filtering and pagination
   * @param options - Query options for filtering users
   * @returns Array of users
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    options?: AllUsersOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<UserSchema[], C, E, P>>;

  /**
   * Get details of a single user
   * @param userId - User ID or username
   * @returns User details
   */
  show<E extends boolean = false>(
    userId: string | number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<UserSchema, C, E, void>>;

  /**
   * Get currently authenticated user
   * @returns Current user details
   */
  current<E extends boolean = false>(
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<UserSchema, C, E, void>>;

  /**
   * Create a new user (admin only)
   * @param options - User configuration
   * @returns Created user
   */
  create<E extends boolean = false>(
    options: CreateUserOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<UserSchema, C, E, void>>;

  /**
   * Update an existing user (admin only)
   * @param userId - User ID
   * @param options - Fields to update
   * @returns Updated user
   */
  edit<E extends boolean = false>(
    userId: number,
    options?: EditUserOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<UserSchema, C, E, void>>;

  /**
   * Block a user (admin only)
   * @param userId - User ID
   * @returns Success status
   */
  block<E extends boolean = false>(
    userId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<boolean, C, E, void>>;

  /**
   * Unblock a user (admin only)
   * @param userId - User ID
   * @returns Success status
   */
  unblock<E extends boolean = false>(
    userId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<boolean, C, E, void>>;
}

Usage Examples:

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({ token: process.env.GITLAB_TOKEN });

// List all users
const users = await api.Users.all({
  active: true,
  orderBy: 'name',
  sort: 'asc'
});

// Search users
const searchResults = await api.Users.all({
  search: 'john',
  perPage: 10
});

// Get specific user
const user = await api.Users.show(123);

// Get current user
const currentUser = await api.Users.current();

// Create new user (admin only)
const newUser = await api.Users.create({
  email: 'newuser@example.com',
  username: 'newuser',
  name: 'New User',
  password: 'secure-password',
  skipConfirmation: true
});

// Update user (admin only)
await api.Users.edit(123, {
  name: 'Updated Name',
  bio: 'Software engineer'
});

// Block user (admin only)
await api.Users.block(123);

// Unblock user (admin only)
await api.Users.unblock(123);

User Query Options

/**
 * Options for filtering and querying users
 */
type AllUsersOptions = {
  /** Order results by field */
  orderBy?: 'name' | 'username' | 'created_at' | 'updated_at';
  /** Filter by user who created them */
  createdBy?: string;
  /** Sort direction */
  sort?: 'asc' | 'desc';
  /** Filter by two-factor authentication */
  twoFactor?: string;
  /** Users without projects */
  withoutProjects?: boolean;
  /** Filter admins only */
  admins?: boolean;
  /** Filter by SAML provider ID */
  samlProviderId?: number;
  /** Skip LDAP users */
  skipLdap?: boolean;
  /** Search term */
  search?: string;
  /** Filter by username */
  username?: string;
  /** Active users only */
  active?: boolean;
  /** Blocked users only */
  blocked?: boolean;
  /** External users */
  external?: boolean;
  /** Exclude internal users */
  excludeInternal?: boolean;
  /** Exclude external users */
  excludeExternal?: boolean;
  /** Exclude project bots */
  withoutProjectBots?: boolean;
  /** Created before date */
  createdBefore?: string;
  /** Created after date */
  createdAfter?: string;
  /** Include custom attributes */
  withCustomAttributes?: boolean;
  /** Filter by custom attributes */
  customAttributes?: Record<string, string>;
  /** Filter by external provider */
  provider?: string;
  /** Filter by external UID */
  externUid?: string;
};

SSH Keys

Manage user SSH keys for Git operations.

/**
 * UserSSHKeys resource class for SSH key management
 */
class UserSSHKeys<C extends boolean = false> {
  /**
   * List SSH keys for a user
   * @param userId - User ID
   * @returns Array of SSH keys
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    userId: number,
    options?: PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<SSHKeySchema[], C, E, P>>;

  /**
   * Get a single SSH key
   * @param userId - User ID
   * @param keyId - SSH key ID
   * @returns SSH key details
   */
  show<E extends boolean = false>(
    userId: number,
    keyId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<SSHKeySchema, C, E, void>>;

  /**
   * Add SSH key for user
   * @param userId - User ID
   * @param title - Key title/name
   * @param key - SSH public key
   * @param options - Additional options (expiresAt, usageType)
   * @returns Created SSH key
   */
  create<E extends boolean = false>(
    userId: number,
    title: string,
    key: string,
    options?: { expiresAt?: string; usageType?: string[] } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<SSHKeySchema, C, E, void>>;

  /**
   * Delete an SSH key
   * @param userId - User ID
   * @param keyId - SSH key ID
   */
  remove<E extends boolean = false>(
    userId: number,
    keyId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

// List user's SSH keys
const keys = await api.UserSSHKeys.all(123);

// Add new SSH key
await api.UserSSHKeys.create(
  123,
  'Work Laptop',
  'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...',
  {
    expiresAt: '2025-12-31',
    usageType: ['auth', 'signing']
  }
);

// Get specific SSH key
const key = await api.UserSSHKeys.show(123, 456);

// Delete SSH key
await api.UserSSHKeys.remove(123, 456);

GPG Keys

Manage user GPG keys for commit signing.

/**
 * UserGPGKeys resource class for GPG key management
 */
class UserGPGKeys<C extends boolean = false> {
  /**
   * List GPG keys for a user
   * @param userId - User ID
   * @returns Array of GPG keys
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    userId: number,
    options?: PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<GPGKeySchema[], C, E, P>>;

  /**
   * Get a single GPG key
   * @param userId - User ID
   * @param keyId - GPG key ID
   * @returns GPG key details
   */
  show<E extends boolean = false>(
    userId: number,
    keyId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<GPGKeySchema, C, E, void>>;

  /**
   * Add GPG key for user
   * @param userId - User ID
   * @param key - GPG public key (armored)
   * @returns Created GPG key
   */
  create<E extends boolean = false>(
    userId: number,
    key: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<GPGKeySchema, C, E, void>>;

  /**
   * Delete a GPG key
   * @param userId - User ID
   * @param keyId - GPG key ID
   */
  remove<E extends boolean = false>(
    userId: number,
    keyId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;

  /**
   * Revoke a GPG key
   * @param userId - User ID
   * @param keyId - GPG key ID
   */
  revoke<E extends boolean = false>(
    userId: number,
    keyId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

// List GPG keys
const gpgKeys = await api.UserGPGKeys.all(123);

// Add GPG key
const gpgKey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----`;
await api.UserGPGKeys.create(123, gpgKey);

// Revoke GPG key
await api.UserGPGKeys.revoke(123, 456);

// Delete GPG key
await api.UserGPGKeys.remove(123, 456);

User Emails

Manage user email addresses.

/**
 * UserEmails resource class for email management
 */
class UserEmails<C extends boolean = false> {
  /**
   * List emails for a user
   * @param userId - User ID
   * @returns Array of email addresses
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    userId: number,
    options?: PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<EmailSchema[], C, E, P>>;

  /**
   * Get a single email
   * @param userId - User ID
   * @param emailId - Email ID
   * @returns Email details
   */
  show<E extends boolean = false>(
    userId: number,
    emailId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<EmailSchema, C, E, void>>;

  /**
   * Add email for user
   * @param userId - User ID
   * @param email - Email address
   * @param options - Skip confirmation option
   * @returns Created email
   */
  create<E extends boolean = false>(
    userId: number,
    email: string,
    options?: { skipConfirmation?: boolean } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<EmailSchema, C, E, void>>;

  /**
   * Delete an email
   * @param userId - User ID
   * @param emailId - Email ID
   */
  remove<E extends boolean = false>(
    userId: number,
    emailId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

// List user emails
const emails = await api.UserEmails.all(123);

// Add new email
await api.UserEmails.create(123, 'additional@example.com', {
  skipConfirmation: true
});

// Get specific email
const email = await api.UserEmails.show(123, 456);

// Delete email
await api.UserEmails.remove(123, 456);

Impersonation Tokens

Manage impersonation tokens for admin use (admin only).

/**
 * UserImpersonationTokens resource class (admin only)
 */
class UserImpersonationTokens<C extends boolean = false> {
  /**
   * List impersonation tokens for a user
   * @param userId - User ID
   * @returns Array of tokens
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    userId: number,
    options?: { state?: 'active' | 'inactive' } & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ImpersonationTokenSchema[], C, E, P>>;

  /**
   * Get a single impersonation token
   * @param userId - User ID
   * @param tokenId - Token ID
   * @returns Token details
   */
  show<E extends boolean = false>(
    userId: number,
    tokenId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ImpersonationTokenSchema, C, E, void>>;

  /**
   * Create an impersonation token
   * @param userId - User ID
   * @param name - Token name
   * @param scopes - Token scopes
   * @param options - Additional options (expiresAt)
   * @returns Created token (includes token value)
   */
  create<E extends boolean = false>(
    userId: number,
    name: string,
    scopes: string[],
    options?: { expiresAt?: string } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ImpersonationTokenSchema & { token: string }, C, E, void>>;

  /**
   * Revoke an impersonation token
   * @param userId - User ID
   * @param tokenId - Token ID
   */
  revoke<E extends boolean = false>(
    userId: number,
    tokenId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

// Create impersonation token (admin only)
const token = await api.UserImpersonationTokens.create(
  123,
  'API Access Token',
  ['api', 'read_user'],
  {
    expiresAt: '2025-12-31'
  }
);
console.log('Token:', token.token); // Save this, it won't be shown again

// List tokens
const tokens = await api.UserImpersonationTokens.all(123, {
  state: 'active'
});

// Revoke token
await api.UserImpersonationTokens.revoke(123, 456);

User Custom Attributes

Store and manage custom metadata for users.

/**
 * UserCustomAttributes resource class
 */
class UserCustomAttributes<C extends boolean = false> {
  /**
   * List all custom attributes for a user
   * @param userId - User ID
   * @returns Array of custom attributes
   */
  all<E extends boolean = false>(
    userId: number,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<CustomAttributeSchema[], C, E, void>>;

  /**
   * Get a single custom attribute
   * @param userId - User ID
   * @param key - Attribute key
   * @returns Custom attribute
   */
  show<E extends boolean = false>(
    userId: number,
    key: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<CustomAttributeSchema, C, E, void>>;

  /**
   * Set a custom attribute
   * @param userId - User ID
   * @param key - Attribute key
   * @param value - Attribute value
   * @returns Custom attribute
   */
  set<E extends boolean = false>(
    userId: number,
    key: string,
    value: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<CustomAttributeSchema, C, E, void>>;

  /**
   * Delete a custom attribute
   * @param userId - User ID
   * @param key - Attribute key
   */
  remove<E extends boolean = false>(
    userId: number,
    key: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

// Set custom attribute
await api.UserCustomAttributes.set(123, 'department', 'Engineering');
await api.UserCustomAttributes.set(123, 'cost_center', 'CC-1234');

// List all custom attributes
const attrs = await api.UserCustomAttributes.all(123);

// Get specific attribute
const dept = await api.UserCustomAttributes.show(123, 'department');

// Delete attribute
await api.UserCustomAttributes.remove(123, 'cost_center');

Related User Resources

Additional resources for user management:

  • PersonalAccessTokens - Manage personal access tokens (admin view)
  • Keys - Instance-level SSH key operations
  • Avatar - Avatar utilities

See Additional Resources for detailed documentation of these resource classes.

Install with Tessl CLI

npx tessl i tessl/npm-gitbeaker--rest

docs

additional-resources.md

cicd.md

client-configuration.md

groups.md

index.md

issues.md

merge-requests.md

package-registries.md

projects.md

repository-management.md

users.md

tile.json