Class UsersService

This resource represent users. Use it to:

  • get, get a list of, create, and delete users.
  • get, set, and reset a user's default issue table columns.
  • get a list of the groups the user belongs to.
  • get a list of user account IDs for a list of usernames or user keys.

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users

Hierarchy

  • CommonHttpService
    • UsersService

Constructors

constructor

Methods

bulkGetUsers bulkGetUsersMigration createUser getAllUsers getAllUsersDefault getUser getUserDefaultColumns getUserEmail getUserEmailBulk getUserGroups removeUser resetUserColumns setUserColumns initialize

Constructors

constructor

  • new UsersService(getClientInstance): UsersService
  • Internal

    Create a new instance of the service.

    Parameters

    • getClientInstance: (() => CommonHttpClient)
        • (): CommonHttpClient

        • Returns CommonHttpClient

    Returns UsersService

Methods

bulkGetUsers

  • bulkGetUsers(params): Promise<PageBeanNullableUser>

  • Returns a paginated list of the users specified by one or more account IDs.

    Permissions required: Permission to access Jira.

    Parameters

    • params: {
          accountId: string[];
          key?: string[];
          maxResults?: number;
          startAt?: number;
          username?: string[];
      }
      • accountId: string[]

        The account ID of a user. To specify multiple users, pass multiple accountId parameters. For example, accountId=5b10a2844c20165700ede21g&accountId=5b10ac8d82e05b22cc7d4ef5.

      • Optionalkey?: string[]

        This parameter is no longer available and will be removed from the documentation soon. See the deprecation notice for details.

      • OptionalmaxResults?: number

        The maximum number of items to return per page.

      • OptionalstartAt?: number

        The index of the first item to return in a page of results (page offset).

      • Optionalusername?: string[]

        This parameter is no longer available and will be removed from the documentation soon. See the deprecation notice for details.

    Returns Promise<PageBeanNullableUser>

    Returned if the request is successful.

    example:

    {
      "isLast": true,
      "maxResults": 100,
      "startAt": 0,
      "total": 1,
      "values": [
        {
          "accountId": "5b10a2844c20165700ede21g",
          "accountType": "atlassian",
          "active": true,
          "avatarUrls": {
            "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
            "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
            "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
            "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
          },
          "displayName": "Mia Krystof",
          "emailAddress": "mia@example.com",
          "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
          "timeZone": "Australia/Sydney"
        }
      ]
    }

    Path

    GET /rest/api/3/user/bulk @scopes-current read:jira-user @scopes-beta read:application-role:jira, read:group:jira, read:user:jira, read:avatar:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-bulk-get

bulkGetUsersMigration

  • bulkGetUsersMigration(params?): Promise<UserMigrationBean[]>

  • Returns the account IDs for the users specified in the key or username parameters. Note that multiple key or username parameters can be specified.

    Permissions required: Permission to access Jira.

    Parameters

    • params: {
          key?: string[];
          maxResults?: number;
          startAt?: number;
          username?: string[];
      } = {}
      • Optionalkey?: string[]

        Key of a user. To specify multiple users, pass multiple copies of this parameter. For example, key=fred&key=barney. Required if username isn't provided. Cannot be provided if username is present.

      • OptionalmaxResults?: number

        The maximum number of items to return per page.

      • OptionalstartAt?: number

        The index of the first item to return in a page of results (page offset).

      • Optionalusername?: string[]

        Username of a user. To specify multiple users, pass multiple copies of this parameter. For example, username=fred&username=barney. Required if key isn't provided. Cannot be provided if key is present.

    Returns Promise<UserMigrationBean[]>

    Returned if the request is successful.

    example:

    [
      {
        "username": "mia",
        "accountId": "5b10a2844c20165700ede21g"
      },
      {
        "username": "emma",
        "accountId": "5b10ac8d82e05b22cc7d4ef5"
      }
    ]

    Path

    GET /rest/api/3/user/bulk/migration @scopes-current read:jira-user @scopes-beta read:user:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-bulk-migration-get

createUser

  • createUser(params): Promise<User>

  • Creates a user. This resource is retained for legacy compatibility. As soon as a more suitable alternative is available this resource will be deprecated.

    If the user exists and has access to Jira, the operation returns a 201 status. If the user exists but does not have access to Jira, the operation returns a 400 status.

    Permissions required: Administer Jira global permission.

    Parameters

    Returns Promise<User>

    Returned if the request is successful.

    example:

    {
      "accountId": "5b10a2844c20165700ede21g",
      "accountType": "atlassian",
      "active": true,
      "applicationRoles": {
        "items": [],
        "size": 1
      },
      "avatarUrls": {
        "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
        "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
        "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
        "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
      },
      "displayName": "Mia Krystof",
      "emailAddress": "mia@example.com",
      "groups": {
        "items": [],
        "size": 3
      },
      "key": "",
      "name": "",
      "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
      "timeZone": "Australia/Sydney"
    }

    Path

    POST /rest/api/3/user

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-post

getAllUsers

  • getAllUsers(params?): Promise<User[]>

  • Returns a list of all users, including active users, inactive users and previously deleted users that have an Atlassian account.

    Privacy controls are applied to the response based on the users' preferences. This could mean, for example, that the user's email address is hidden. See the Profile visibility overview for more details.

    Permissions required: Browse users and groups global permission.

    Parameters

    • params: {
          maxResults?: number;
          startAt?: number;
      } = {}
      • OptionalmaxResults?: number

        The maximum number of items to return.

      • OptionalstartAt?: number

        The index of the first item to return.

    Returns Promise<User[]>

    Returned if the request is successful.

    example:

    [
      {
        "accountId": "5b10a2844c20165700ede21g",
        "accountType": "atlassian",
        "active": false,
        "avatarUrls": {
          "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
          "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
          "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
          "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
        },
        "displayName": "Mia Krystof",
        "key": "",
        "name": "",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
      },
      {
        "accountId": "5b10ac8d82e05b22cc7d4ef5",
        "accountType": "atlassian",
        "active": false,
        "avatarUrls": {
          "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=16&s=16",
          "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=24&s=24",
          "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=32&s=32",
          "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=48&s=48"
        },
        "displayName": "Emma Richards",
        "key": "",
        "name": "",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10ac8d82e05b22cc7d4ef5"
      }
    ]

    Path

    GET /rest/api/3/users/search @scopes-current read:jira-user @scopes-beta read:user:jira, read:application-role:jira, read:avatar:jira, read:group:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-users-search-get

getAllUsersDefault

  • getAllUsersDefault(params?): Promise<User[]>

  • Returns a list of all users, including active users, inactive users and previously deleted users that have an Atlassian account.

    Privacy controls are applied to the response based on the users' preferences. This could mean, for example, that the user's email address is hidden. See the Profile visibility overview for more details.

    Permissions required: Browse users and groups global permission.

    Parameters

    • params: {
          maxResults?: number;
          startAt?: number;
      } = {}
      • OptionalmaxResults?: number

        The maximum number of items to return.

      • OptionalstartAt?: number

        The index of the first item to return.

    Returns Promise<User[]>

    Returned if the request is successful.

    example:

    [
      {
        "accountId": "5b10a2844c20165700ede21g",
        "accountType": "atlassian",
        "active": false,
        "avatarUrls": {
          "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
          "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
          "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
          "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
        },
        "displayName": "Mia Krystof",
        "key": "",
        "name": "",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
      },
      {
        "accountId": "5b10ac8d82e05b22cc7d4ef5",
        "accountType": "atlassian",
        "active": false,
        "avatarUrls": {
          "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=16&s=16",
          "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=24&s=24",
          "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=32&s=32",
          "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/AA-3.png?size=48&s=48"
        },
        "displayName": "Emma Richards",
        "key": "",
        "name": "",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10ac8d82e05b22cc7d4ef5"
      }
    ]

    Path

    GET /rest/api/3/users @scopes-current read:jira-user @scopes-beta read:user:jira, read:application-role:jira, read:avatar:jira, read:group:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-users-get

getUser

  • getUser(params?): Promise<User>

  • Returns a user.

    Privacy controls are applied to the response based on the user's preferences. This could mean, for example, that the user's email address is hidden. See the Profile visibility overview for more details.

    Permissions required: Browse users and groups global permission.

    Parameters

    • params: {
          accountId?: string;
          expand?: string;
          key?: string;
          username?: string;
      } = {}
      • OptionalaccountId?: string

        The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5. Required.

      • Optionalexpand?: string

        Use expand to include additional information about users in the response. This parameter accepts a comma-separated list. Expand options include:

        • groups includes all groups and nested groups to which the user belongs.
        • applicationRoles includes details of all the applications to which the user has access.
      • Optionalkey?: string

        This parameter is no longer available. See the deprecation notice for details.

      • Optionalusername?: string

        This parameter is no longer available. See the deprecation notice for details.

    Returns Promise<User>

    Returned if the request is successful.

    example:

    {
      "accountId": "5b10a2844c20165700ede21g",
      "accountType": "atlassian",
      "active": true,
      "applicationRoles": {
        "items": [],
        "size": 1
      },
      "avatarUrls": {
        "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
        "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
        "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
        "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
      },
      "displayName": "Mia Krystof",
      "emailAddress": "mia@example.com",
      "groups": {
        "items": [],
        "size": 3
      },
      "key": "",
      "name": "",
      "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
      "timeZone": "Australia/Sydney"
    }

    Path

    GET /rest/api/3/user @scopes-current read:jira-user @scopes-beta read:application-role:jira, read:group:jira, read:user:jira, read:avatar:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-get

getUserDefaultColumns

  • getUserDefaultColumns(params?): Promise<ColumnItem[]>

  • Returns the default issue table columns for the user. If accountId is not passed in the request, the calling user's details are returned.

    Permissions required:

    • Administer Jira global permission, to get the column details for any user.
    • Permission to access Jira, to get the calling user's column details.

    Parameters

    • params: {
          accountId?: string;
          username?: string;
      } = {}
      • OptionalaccountId?: string

        The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.

      • Optionalusername?: string

        This parameter is no longer available See the deprecation notice for details.

    Returns Promise<ColumnItem[]>

    Returned if the request is successful.

    Path

    GET /rest/api/3/user/columns @scopes-current read:jira-user @scopes-beta read:user.columns:jira, read:filter.column:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-columns-get

getUserEmail

  • getUserEmail(params): Promise<UnrestrictedUserEmail>

  • Returns a user's email address regardless of the user's profile visibility settings. For Connect apps, this API is only available to apps approved by Atlassian, according to these guidelines. For Forge apps, this API only supports access via asApp() requests.

    Parameters

    • params: {
          accountId: string;
      }
      • accountId: string

        The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.

    Returns Promise<UnrestrictedUserEmail>

    Returned if the request is successful.

    example:

    name@example.com

    Path

    GET /rest/api/3/user/email @scopes-beta read:email-address:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-email-get

getUserEmailBulk

  • getUserEmailBulk(params): Promise<UnrestrictedUserEmail>

  • Returns a user's email address regardless of the user's profile visibility settings. For Connect apps, this API is only available to apps approved by Atlassian, according to these guidelines. For Forge apps, this API only supports access via asApp() requests.

    Parameters

    • params: {
          accountId: string[];
      }
      • accountId: string[]

        The account IDs of the users for which emails are required. An accountId is an identifier that uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5. Note, this should be treated as an opaque identifier (that is, do not assume any structure in the value).

    Returns Promise<UnrestrictedUserEmail>

    Returned if the request is successful.

    Path

    GET /rest/api/3/user/email/bulk @scopes-beta read:email-address:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-email-bulk-get

getUserGroups

  • getUserGroups(params): Promise<GroupName[]>

  • Returns the groups to which a user belongs.

    Permissions required: Browse users and groups global permission.

    Parameters

    • params: {
          accountId: string;
          key?: string;
          username?: string;
      }
      • accountId: string

        The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.

      • Optionalkey?: string

        This parameter is no longer available. See the deprecation notice for details.

      • Optionalusername?: string

        This parameter is no longer available. See the deprecation notice for details.

    Returns Promise<GroupName[]>

    Returned if the request is successful.

    example:

    {
      "groupId": "276f955c-63d7-42c8-9520-92d01dca0625",
      "name": "jira-administrators",
      "self": "https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625"
    }

    Path

    GET /rest/api/3/user/groups @scopes-current read:jira-user @scopes-beta read:group:jira

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-groups-get

removeUser

  • removeUser(params): Promise<void>

  • Deletes a user. If the operation completes successfully then the user is removed from Jira's user base. This operation does not delete the user's Atlassian account.

    Permissions required: Site administration (that is, membership of the site-admin group).

    Parameters

    • params: {
          accountId: string;
          key?: string;
          username?: string;
      }
      • accountId: string

        The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.

      • Optionalkey?: string

        This parameter is no longer available. See the deprecation notice for details.

      • Optionalusername?: string

        This parameter is no longer available. See the deprecation notice for details.

    Returns Promise<void>

    Path

    DELETE /rest/api/3/user

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-delete

resetUserColumns

setUserColumns

  • setUserColumns(params): Promise<unknown>

  • Sets the default issue table columns for the user. If an account ID is not passed, the calling user's default columns are set. If no column details are sent, then all default columns are removed.

    The parameters for this resource are expressed as HTML form data. For example, in curl:

    curl -X PUT -d columns=summary -d columns=description https://your-domain.atlassian.net/rest/api/3/user/columns?accountId=5b10ac8d82e05b22cc7d4ef5'

    Permissions required:

    • Administer Jira global permission, to set the columns on any user.
    • Permission to access Jira, to set the calling user's columns.

    Parameters

    • params: {
          accountId?: string;
          userColumnRequestBody: UserColumnRequestBody;
      }
      • OptionalaccountId?: string

        The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.

      • userColumnRequestBody: UserColumnRequestBody

        The ID of a column to set. To set multiple columns, send multiple columns parameters.

    Returns Promise<unknown>

    Returned if the request is successful.

    Path

    PUT /rest/api/3/user/columns

    See

    https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users#api-rest-api-3-user-columns-put

Protected Staticinitialize

  • initialize(): void

  • Method to initialize the class. Normally used to set up validation rules.

    Returns void

Settings

Member Visibility

On This Page

Constructors
Methods