You are here

Home » API reference » Auth0 Single Sign On 8.2 » Users.php

class Users in Auth0 Single Sign On 8.2

Class Users. Handles requests to the Users endpoint of the v2 Management API.

@package Auth0\SDK\API\Management

Hierarchy

Expanded class hierarchy of Users

1 file declares its use of Users
Management.php in vendor/auth0/auth0-php/src/API/Management.php

File

vendor/auth0/auth0-php/src/API/Management/Users.php, line 14

Namespace

Auth0\SDK\API\Management
View source 
class Users extends GenericResource {

  /**
   * Get a single User by ID.
   * Required scopes:
   *      - "read:users" - For any call to this endpoint.
   *      - "read:user_idp_tokens" - To retrieve the "access_token" field for logged-in identities.
   *
   * @param string $user_id User ID to get.
   *
   * @return mixed
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   */
  public function get($user_id) {
    return $this->apiClient
      ->method('get')
      ->addPath('users', $user_id)
      ->call();
  }

  /**
   * Update a User.
   * Required scopes:
   *      - "update:users" - For any call to this endpoint.
   *      - "update:users_app_metadata" - For any update that includes "user_metadata" or "app_metadata" fields.
   *
   * @param string $user_id User ID to update.
   * @param array  $data    User data to update:
   *          - Only certain fields can be updated; see the @link below for allowed fields.
   *          - "user_metadata" and "app_metadata" fields are merged, not replaced.
   *
   * @return mixed|string
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id
   */
  public function update($user_id, array $data) {
    return $this->apiClient
      ->method('patch')
      ->addPath('users', $user_id)
      ->withBody(json_encode($data))
      ->call();
  }

  /**
   * Create a new User.
   * Required scope: "create:users"
   *
   * @param array $data User create data:
   *      - "connection" name field is required and limited to sms, email, & DB connections.
   *      - "phone_number" field is required by sms connections.
   *      - "email" field is required by email and DB connections.
   *      - "password" field is required by DB connections.
   *      - Depending on the connection used, may also require a "username" field.
   *
   * @return mixed|string
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/post_users
   */
  public function create(array $data) {
    if (empty($data['connection'])) {
      throw new \Exception('Missing required "connection" field.');
    }

    // A phone number is required for sms connections.
    if ('sms' === $data['connection'] && empty($data['phone_number'])) {
      throw new \Exception('Missing required "phone_number" field for sms connection.');
    }

    // An email is required for email and DB connections.
    if ('sms' !== $data['connection'] && empty($data['email'])) {
      throw new \Exception('Missing required "email" field.');
    }

    // A password is required for DB connections.
    if (!in_array($data['connection'], [
      'email',
      'sms',
    ]) && empty($data['password'])) {
      throw new \Exception('Missing required "password" field for "' . $data['connection'] . '" connection.');
    }
    return $this->apiClient
      ->method('post')
      ->addPath('users')
      ->withBody(json_encode($data))
      ->call();
  }

  /**
   * Search all Users.
   * Required scopes:
   *      - "read:users" - For any call to this endpoint.
   *      - "read:user_idp_tokens" - To retrieve the "access_token" field for logged-in identities.
   *
   * @param array             $params         Search parameters to send:
   *      - "fields", "include_fields", "page", and "per_page" keys here will override the explicit parameters.
   *      - Queries using "search_engine" set to "v2" should be migrated to v3; see search v3 @link below.
   * @param null|string|array $fields         Fields to include or exclude from the result.
   *      - Including only the fields required can speed up API calls significantly.
   *      - Arrays will be converted to comma-separated strings.
   * @param null|boolean      $include_fields True to include $fields, false to exclude $fields.
   * @param null|integer      $page           Page number to get, zero-based.
   * @param null|integer      $per_page       Number of results to get, null to return the default number.
   *
   * @return mixed
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @link https://auth0.com/docs/users/search/v3
   * @link https://auth0.com/docs/api/management/v2#!/Users/get_users
   */
  public function getAll(array $params = [], $fields = null, $include_fields = null, $page = null, $per_page = null) {

    // Fields to include/exclude.
    if (!isset($params['fields']) && null !== $fields) {
      $params['fields'] = $fields;
    }
    if (isset($params['fields'])) {
      if (is_array($params['fields'])) {
        $params['fields'] = implode(',', $params['fields']);
      }
      if (!isset($params['include_fields']) && null !== $include_fields) {
        $params['include_fields'] = (bool) $include_fields;
      }
    }
    $params = $this
      ->normalizePagination($params, $page, $per_page);
    return $this->apiClient
      ->method('get')
      ->addPath('users')
      ->withDictParams($params)
      ->call();
  }

  /**
   * Delete a User by ID.
   * Required scope: "delete:users"
   *
   * @param string $user_id User ID to delete.
   *
   * @return mixed|string
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/delete_users_by_id
   */
  public function delete($user_id) {
    return $this->apiClient
      ->method('delete')
      ->addPath('users', $user_id)
      ->call();
  }

  /**
   * Link one user identity to another.
   * Required scope: "update:users"
   *
   * @param string $user_id User ID of the primary account.
   * @param array  $data    An array with the following fields:
   *          - "provider" - Secondary account provider.
   *          - "user_id" - Secondary account user ID.
   *          - "connection_id" - Secondary account Connection ID (optional).
   *
   * @return array Array of the primary account identities after the merge.
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/post_identities
   */
  public function linkAccount($user_id, array $data) {
    return $this->apiClient
      ->method('post')
      ->addPath('users', $user_id)
      ->addPath('identities')
      ->withBody(json_encode($data))
      ->call();
  }

  /**
   * Unlink an identity from the target user.
   * Required scope: "update:users"
   *
   * @param string $user_id     User ID to unlink.
   * @param string $provider    Identity provider of the secondary linked account.
   * @param string $identity_id The unique identifier of the secondary linked account.
   *
   * @return mixed|string
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/delete_user_identity_by_user_id
   */
  public function unlinkAccount($user_id, $provider, $identity_id) {
    return $this->apiClient
      ->method('delete')
      ->addPath('users', $user_id)
      ->addPath('identities', $provider)
      ->addPath($identity_id)
      ->call();
  }

  /**
   * Delete the multifactor provider settings for a particular user.
   * This will force user to re-configure the multifactor provider.
   * Required scope: "update:users"
   *
   * @param string $user_id      User ID with the multifactor provider to delete.
   * @param string $mfa_provider Multifactor provider to delete.
   *
   * @return mixed|string
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/delete_multifactor_by_provider
   */
  public function deleteMultifactorProvider($user_id, $mfa_provider) {
    return $this->apiClient
      ->method('delete')
      ->addPath('users', $user_id)
      ->addPath('multifactor', $mfa_provider)
      ->call();
  }

  /**
   * Get all roles assigned to a specific user.
   * Required scopes:
   *      - "read:users"
   *      - "read:roles"
   *
   * @param string $user_id User ID to get roles for.
   * @param array  $params  Additional listing params like page, per_page, and include_totals.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/get_user_roles
   */
  public function getRoles($user_id, array $params = []) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    $params = $this
      ->normalizePagination($params);
    $params = $this
      ->normalizeIncludeTotals($params);
    return $this->apiClient
      ->method('get')
      ->addPath('users', $user_id)
      ->addPath('roles')
      ->withDictParams($params)
      ->call();
  }

  /**
   * Remove one or more roles from a specific user.
   * Required scope: "update:users"
   *
   * @param string $user_id User ID to remove roles from.
   * @param array  $roles   Array of permissions to remove.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws EmptyOrInvalidParameterException Thrown if the roles parameter is empty.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/delete_user_roles
   */
  public function removeRoles($user_id, array $roles) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    if (empty($roles)) {
      throw new EmptyOrInvalidParameterException('roles');
    }
    $data = [
      'roles' => $roles,
    ];
    return $this->apiClient
      ->method('delete')
      ->addPath('users', $user_id)
      ->addPath('roles')
      ->withBody(json_encode($data))
      ->call();
  }

  /**
   * Add one or more roles to a specific user.
   * Required scopes:
   *      - "update:users"
   *      - "read:roles"
   *
   * @param string $user_id User ID to add roles to.
   * @param array  $roles   Array of roles to add.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws EmptyOrInvalidParameterException Thrown if the roles parameter is empty.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/post_user_roles
   */
  public function addRoles($user_id, array $roles) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    if (empty($roles)) {
      throw new EmptyOrInvalidParameterException('roles');
    }
    $data = [
      'roles' => $roles,
    ];
    return $this->apiClient
      ->method('post')
      ->addPath('users', $user_id)
      ->addPath('roles')
      ->withBody(json_encode($data))
      ->call();
  }

  /**
   * Get all Guardian enrollments for a specific user.
   * Required scope: "read:users"
   *
   * @param string $user_id User ID to get enrollments for.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/get_enrollments
   */
  public function getEnrollments($user_id) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    return $this->apiClient
      ->method('get')
      ->addPath('users', $user_id)
      ->addPath('enrollments')
      ->call();
  }

  /**
   * Get all permissions for a specific user.
   * Required scope: "read:users"
   *
   * @param string $user_id User ID to get permissions for.
   * @param array  $params  Additional listing params like page, per_page, and include_totals.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/get_permissions
   */
  public function getPermissions($user_id, array $params = []) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    $params = $this
      ->normalizePagination($params);
    $params = $this
      ->normalizeIncludeTotals($params);
    return $this->apiClient
      ->method('get')
      ->addPath('users', $user_id)
      ->addPath('permissions')
      ->withDictParams($params)
      ->call();
  }

  /**
   * Remove one or more permissions from a specific user.
   * Required scope: "update:users"
   *
   * @param string $user_id     User ID to remove permissions from.
   * @param array  $permissions Array of permissions to remove.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws InvalidPermissionsArrayException Thrown if the permissions parameter is malformed.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/delete_permissions
   */
  public function removePermissions($user_id, array $permissions) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    $this
      ->checkInvalidPermissions($permissions);
    $data = [
      'permissions' => $permissions,
    ];
    return $this->apiClient
      ->method('delete')
      ->addPath('users', $user_id)
      ->addPath('permissions')
      ->withBody(json_encode($data))
      ->call();
  }

  /**
   * Add one or more permissions to a specific user.
   * Required scope: "update:users"
   *
   * @param string $user_id     User ID to add permissions to.
   * @param array  $permissions Array of permissions to add.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws InvalidPermissionsArrayException Thrown if the permissions parameter is malformed.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/post_permissions
   */
  public function addPermissions($user_id, array $permissions) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    $this
      ->checkInvalidPermissions($permissions);
    $data = [
      'permissions' => $permissions,
    ];
    return $this->apiClient
      ->method('post')
      ->addPath('users', $user_id)
      ->addPath('permissions')
      ->withBody(json_encode($data))
      ->call();
  }

  /**
   * Get log entries for a specific user.
   * Required scope: "read:logs"
   *
   * @param string $user_id User ID to get logs entries for.
   * @param array  $params  Additional listing params like page, per_page, sort, and include_totals.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/get_logs_by_user
   */
  public function getLogs($user_id, array $params = []) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    $params = $this
      ->normalizePagination($params);
    $params = $this
      ->normalizeIncludeTotals($params);
    return $this->apiClient
      ->method('get')
      ->addPath('users', $user_id)
      ->addPath('logs')
      ->withDictParams($params)
      ->call();
  }

  /**
   * Removes the current Guardian recovery code and generates and returns a new one.
   * Required scope: "update:users"
   *
   * @param string $user_id User ID to remove and generate recovery codes for.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/post_recovery_code_regeneration
   */
  public function generateRecoveryCode($user_id) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    return $this->apiClient
      ->method('post')
      ->addPath('users', $user_id)
      ->addPath('recovery-code-regeneration')
      ->call();
  }

  /**
   * Invalidates all remembered browsers for all authentication factors for a specific user.
   * Required scope: "update:users"
   *
   * @param string $user_id User ID to invalidate browsers for.
   *
   * @throws EmptyOrInvalidParameterException Thrown if the user_id parameter is empty or is not a string.
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @return mixed
   *
   * @link https://auth0.com/docs/api/management/v2#!/Users/post_invalidate_remember_browser
   */
  public function invalidateBrowsers($user_id) {
    $this
      ->checkEmptyOrInvalidString($user_id, 'user_id');
    return $this->apiClient
      ->method('post')
      ->addPath('users', $user_id)
      ->addPath('multifactor/actions/invalidate-remember-browser')
      ->call();
  }

  /*
   * Deprecated
   */

  // phpcs:disable

  /**
   * Wrapper for self::getAll().
   *
   * @deprecated 5.4.0, use $this->getAll instead.
   *
   * @param array $params Search parameters to send.
   *
   * @return mixed|string
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @codeCoverageIgnores - Deprecated
   */
  public function search(array $params = []) {
    return $this
      ->getAll($params);
  }

  /**
   * Unlink device.
   *
   * @deprecated 5.4.0, endpoint does not exist.
   *
   * @param string $user_id   User ID.
   * @param string $device_id Device ID.
   *
   * @return void
   *
   * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
   *
   * @codeCoverageIgnores - Deprecated
   */
  public function unlinkDevice($user_id, $device_id) {
    throw new \Exception('Endpoint /api/v2/users/{user_id}/devices/{device_id} does not exist.');
  }

}

Members

Namesort descending Modifiers Type Description Overrides
GenericResource::$apiClient protected property Injected ApiClient instance to use.
GenericResource::checkEmptyOrInvalidString protected function Check that a variable is a string and is not empty.
GenericResource::checkInvalidPermissions protected function Check for invalid permissions with an array of permissions.
GenericResource::getApiClient public function Get the injected ApiClient instance.
GenericResource::normalizeIncludeTotals protected function Normalize include_totals parameter.
GenericResource::normalizePagination protected function Normalize pagination parameters.
GenericResource::__construct public function GenericResource constructor.
Users::addPermissions public function Add one or more permissions to a specific user. Required scope: "update:users"
Users::addRoles public function Add one or more roles to a specific user. Required scopes:
Users::create public function Create a new User. Required scope: "create:users"
Users::delete public function Delete a User by ID. Required scope: "delete:users"
Users::deleteMultifactorProvider public function Delete the multifactor provider settings for a particular user. This will force user to re-configure the multifactor provider. Required scope: "update:users"
Users::generateRecoveryCode public function Removes the current Guardian recovery code and generates and returns a new one. Required scope: "update:users"
Users::get public function Get a single User by ID. Required scopes:
Users::getAll public function Search all Users. Required scopes:
Users::getEnrollments public function Get all Guardian enrollments for a specific user. Required scope: "read:users"
Users::getLogs public function Get log entries for a specific user. Required scope: "read:logs"
Users::getPermissions public function Get all permissions for a specific user. Required scope: "read:users"
Users::getRoles public function Get all roles assigned to a specific user. Required scopes:
Users::invalidateBrowsers public function Invalidates all remembered browsers for all authentication factors for a specific user. Required scope: "update:users"
Users::linkAccount public function Link one user identity to another. Required scope: "update:users"
Users::removePermissions public function Remove one or more permissions from a specific user. Required scope: "update:users"
Users::removeRoles public function Remove one or more roles from a specific user. Required scope: "update:users"
Users::search Deprecated public function Wrapper for self::getAll().
Users::unlinkAccount public function Unlink an identity from the target user. Required scope: "update:users"
Users::unlinkDevice Deprecated public function Unlink device.
Users::update public function Update a User. Required scopes: