1. Docs
  2. Reference
  3. REST API Docs
  4. Users

Users

    The Users API covers user profile management, identity linking, and account settings for the authenticated Pulumi user.

    Get Current User

    ▼
    GET /api/user

    Returns the authenticated user’s profile information, including login name, display name, email, avatar URL, and organization memberships.

    Responses

    200 OK
    Schema: User
    • id string required
      The unique identifier of the user.
    • githubLogin string required
      The user’s login name (originally from GitHub).
    • name string required
      The user’s display name.
    • email string required
      The user’s email address.
    • avatarUrl string required
      The URL of the user’s avatar image.
    • organizations array[OrganizationSummaryWithRole] required
      Organizations is the list of Pulumi organizations the user is a member of.
    • ↳ name string required
      The name of the organization.
    • ↳ role enum optional
      The role of the user within this organization.
      Values: none, member, admin, potential-member, stack-collaborator, billing-manager
    • ↳ githubLogin string required
      The GitHub login associated with the organization.
    • ↳ avatarUrl string required
      The URL of the organization’s avatar image.
    • ↳ email string optional
      IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.
    • potentialOrganizations array[OrganizationSummaryWithRole] optional
      PotentialOrganizations is the list of Pulumi organizations the user is a potential member of.
    • ↳ name string required
      The name of the organization.
    • ↳ role enum optional
      The role of the user within this organization.
      Values: none, member, admin, potential-member, stack-collaborator, billing-manager
    • ↳ githubLogin string required
      The GitHub login associated with the organization.
    • ↳ avatarUrl string required
      The URL of the organization’s avatar image.
    • ↳ email string optional
      IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.
    • identities array[string] required
      Identities is the array of identities a Pulumi user’s account is tied to.
    • siteAdmin boolean optional
      SiteAdministrator is whether or not the user is a site administrator.
    • registryAdmin boolean optional
      RegistryAdmin is whether or not the user is a registry administrator.
    • tokenInfo TokenInfo optional
      TokenInfo is contains metadata, set only for machine tokens & to be used only in the CLI
    • ↳ name string required
      The name of the access token.
    • ↳ organization string required
      The organization the token is scoped to, if any.
    • ↳ team string required
      The team the token is scoped to, if any.
    • hasMFA boolean required
      Whether the user has multi-factor authentication enabled.
    • isOrgManaged boolean required
      Whether the user’s account is managed by an organization.
    • isManagedByMultiOrg boolean required
      Whether the user’s account is managed by multiple organizations.

    List GitHub Organization Teams

    ▼
    GET /api/user/github/{ghOrgName}/teams

    ListGitHubOrganizationTeams returns all GitHub teams the requesting user has access to see.

    Request Parameters

    • ghOrgName string path required
      The GitHub organization name

    Responses

    200 OK
    Schema: ListGitHubOrganizationTeamsResponse
    • teams array[GitHubTeam] required
      The list of GitHub teams in the organization
    • ↳ id integer required
      The GitHub team ID
    • ↳ name string required
      The team name
    • ↳ slug string required
      The team slug (URL-friendly name)
    • ↳ description string required
      The team description
    • ↳ knownToPulumi boolean required
      Whether the team is known to Pulumi
    Errors: 400 operation only supported for GitHub-backed users 404 Organization

    Get Groups For GitLab App

    ▼
    Deprecated.
    GET /api/user/gitlab-app/organizations

    Gets a list of GitLab groups available to be used with the Pulumi GitLab app. This endpoint explicitly denotes which groups can be used based on the user’s permissions within each group.

    Responses

    200 successful operation

    Update Default Organization

    ▼
    POST /api/user/organizations/{orgName}/default

    UpdateDefaultOrganization sets the default organization for the current user.

    Request Parameters

    • orgName string path required
      The organization name

    Responses

    204 No Content

    Get Default Organization

    ▼
    GET /api/user/organizations/default

    GetDefaultOrganization returns the default organization for the current user.

    Responses

    200 OK
    Schema: AppGetDefaultOrganizationResponse
    • GitHubLogin string required
      Returns the organization name. Can be an empty string, if the user is a member of no organizations
    • Messages array[AppMessage] required
      Messages is a list of messages that should be displayed to the user that contextualize the default org; for example: warning new users if their default org as returned by the service is on an expiring trial and not free tier, with possible recommendations on how to configure their default org locally. Can be possibly empty.
    • ↳ severity enum optional
      Severity is the severity of the message.
      Values: warning, error, info
    • ↳ message string required
      Message is the message to display to the user.
    Errors: 400 User is not a member of any organizations.

    Get Latest Pending Email Change

    ▼
    GET /api/user/pending-emails

    GetLatestPendingEmailChange returns only the latest email change, that is pending. Returns a 204 if no pending email change requests exist.

    Responses

    200 OK
    Schema: GetPendingEmailVerificationResponse
    • email string required
      The pending email address awaiting verification
    204 No Content

    Delete Pending Email Change

    ▼
    DELETE /api/user/pending-emails

    DeletePendingEmailChange removes the pending email change for the currently logged-in user. Deletes the pending verification only if it isn’t a verification record for the current primary email itself.

    Responses

    204 No Content
    Errors: 400 Cannot delete the pending verification for primary email.

    List User Org Invites

    ▼
    GET /api/user/pending-invites

    ListUserOrgInvites lists the pending invites for the requesting user.

    Responses

    200 OK
    Schema: ListOrganizationInvitesResponse
    • invites array[PendingOrganizationInvite] required
      The list of pending organization invites
    • ↳ id string required
      ID is the internal ID of the invite. Used to refer to this invite later to accept/cancel.
    • ↳ email string required
      The email address the invite was sent to.
    • ↳ role enum required
      Role is the new role to give the member. Must be one of MEMBER, ADMIN, or BILLING MANAGER.
      Values: none, member, admin, potential-member, stack-collaborator, billing-manager
    • ↳ sentBy UserInfo required
      The user who sent the invite.
    • ↳ sentAt integer required
      SentAt is the timestamp when the invite was first sent.
    • ↳ acceptInviteUrl string required
      AcceptInviteURL is the url where a user would go to accept an invite to an organization.
    • ↳ acceptError string optional
      AcceptError is the most recent error a user has hit while trying to accept an organization invite. By default it is null.
    • ↳ status string required
      The friendly name of the invite status. Valid values are “pending”, “accepted”, “expired”, and “canceled”.
    • ↳ roleId string optional
      RoleID is the optional UUID of a custom role assigned to this invite.

    List User Stacks

    ▼
    GET /api/user/stacks

    Lists all stacks accessible to the authenticated user. Results can be filtered by organization, project, and stack tags (tagName/tagValue). Supports pagination via continuationToken and maxResults parameters. Returns stack summary information including name, project, last update status, and resource count.

    Request Parameters

    • continuationToken string query optional
      Token from a previous response to fetch the next page of results
    • maxResults integer query optional
      Maximum number of stacks to return per page
    • organization string query optional
      Filter stacks to those owned by this organization
    • project string query optional
      Filter stacks to those in this project
    • roleID string query optional
      List stacks only using this custom role
    • tagName string query optional
      Filter stacks by tag name (use with tagValue for exact match)
    • tagValue string query optional
      Filter stacks by tag value (requires tagName)

    Responses

    200 OK
    Schema: AppListStacksResponse
    • stacks array[AppStackSummary] required
      List of stacks
    • ↳ id string required
      The logical identifier of the stack.
    • ↳ orgName string required
      OrgName is the organization name the stack is found in.
    • ↳ projectName string required
      ProjectName is the name of the project the stack is associated with.
    • ↳ stackName string required
      StackName is the name of the stack.
    • ↳ lastUpdate integer optional
      LastUpdate is a Unix timestamp of the start time of the stack’s last update, as applicable.
    • ↳ resourceCount integer optional
      ResourceCount is the number of resources associated with this stack, as applicable.
    • ↳ links AppStackLinks optional
      Links to the stack in the Pulumi Console
    • continuationToken string optional

      ContinuationToken is an opaque value used to mark the end of the all stacks. If non-nil, pass it into a subsequent call in order to get the next batch of results.

      A value of nil means that all stacks have been returned.

    Errors: 400 Invalid continuation token

    Delete Identity Provider

    ▼
    DELETE /api/user/vcs

    DeleteIdentityProvider removes a VCS identity provider from the current user’s account.

    Request Parameters

    • identity string query optional
      The VCS identity provider to disconnect (e.g., github, gitlab, bitbucket)

    Responses

    200 OK
    Schema: User
    • id string required
      The unique identifier of the user.
    • githubLogin string required
      The user’s login name (originally from GitHub).
    • name string required
      The user’s display name.
    • email string required
      The user’s email address.
    • avatarUrl string required
      The URL of the user’s avatar image.
    • organizations array[OrganizationSummaryWithRole] required
      Organizations is the list of Pulumi organizations the user is a member of.
    • ↳ name string required
      The name of the organization.
    • ↳ role enum optional
      The role of the user within this organization.
      Values: none, member, admin, potential-member, stack-collaborator, billing-manager
    • ↳ githubLogin string required
      The GitHub login associated with the organization.
    • ↳ avatarUrl string required
      The URL of the organization’s avatar image.
    • ↳ email string optional
      IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.
    • potentialOrganizations array[OrganizationSummaryWithRole] optional
      PotentialOrganizations is the list of Pulumi organizations the user is a potential member of.
    • ↳ name string required
      The name of the organization.
    • ↳ role enum optional
      The role of the user within this organization.
      Values: none, member, admin, potential-member, stack-collaborator, billing-manager
    • ↳ githubLogin string required
      The GitHub login associated with the organization.
    • ↳ avatarUrl string required
      The URL of the organization’s avatar image.
    • ↳ email string optional
      IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.
    • identities array[string] required
      Identities is the array of identities a Pulumi user’s account is tied to.
    • siteAdmin boolean optional
      SiteAdministrator is whether or not the user is a site administrator.
    • registryAdmin boolean optional
      RegistryAdmin is whether or not the user is a registry administrator.
    • tokenInfo TokenInfo optional
      TokenInfo is contains metadata, set only for machine tokens & to be used only in the CLI
    • ↳ name string required
      The name of the access token.
    • ↳ organization string required
      The organization the token is scoped to, if any.
    • ↳ team string required
      The team the token is scoped to, if any.
    • hasMFA boolean required
      Whether the user has multi-factor authentication enabled.
    • isOrgManaged boolean required
      Whether the user’s account is managed by an organization.
    • isManagedByMultiOrg boolean required
      Whether the user’s account is managed by multiple organizations.
    Errors: 400 must have more than one identity provider 404 organizations

    List Identity Provider Organizations

    ▼
    GET /api/user/vcs/organizations

    ListIdentityProviderOrganizations lists all of the organizations from a backing VCS visible to the Pulumi Service for the requesting user. Ignores errors if this user doesn’t have a specific backing identity.

    Responses

    200 OK
    Schema: ListGitHubOrganizationsResponse
    • organizations array[PulumiGitHubOrganization] required
      The list of GitHub organizations
    • ↳ organization UserInfo required
      Organization data from GitHub.
    • ↳ vcsKind enum required
      The identity provider associated with this GitHub organization.
      Values: dev.azure.com, bitbucket.org, github.com, gitlab.com, google.com, Pulumi, SAML
    • ↳ knownToPulumi boolean required
      KnownToPulumi is true if there is a Pulumi organization backed by the GitHub organization.

    Sync With Identity Provider

    ▼
    POST /api/user/vcs/sync

    SyncWithIdentityProvider contacts the requesting user’s identity provider, and updates their profile information (display name, avatar URL, etc.) This is required since we don’t get update events from the identity provider when changes are made in the identity provider’s system.

    Request Parameters

    • identity string query optional
      The VCS identity provider to sync profile data from (e.g., github, gitlab)

    Responses

    200 OK
    Schema: User
    • id string required
      The unique identifier of the user.
    • githubLogin string required
      The user’s login name (originally from GitHub).
    • name string required
      The user’s display name.
    • email string required
      The user’s email address.
    • avatarUrl string required
      The URL of the user’s avatar image.
    • organizations array[OrganizationSummaryWithRole] required
      Organizations is the list of Pulumi organizations the user is a member of.
    • ↳ name string required
      The name of the organization.
    • ↳ role enum optional
      The role of the user within this organization.
      Values: none, member, admin, potential-member, stack-collaborator, billing-manager
    • ↳ githubLogin string required
      The GitHub login associated with the organization.
    • ↳ avatarUrl string required
      The URL of the organization’s avatar image.
    • ↳ email string optional
      IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.
    • potentialOrganizations array[OrganizationSummaryWithRole] optional
      PotentialOrganizations is the list of Pulumi organizations the user is a potential member of.
    • ↳ name string required
      The name of the organization.
    • ↳ role enum optional
      The role of the user within this organization.
      Values: none, member, admin, potential-member, stack-collaborator, billing-manager
    • ↳ githubLogin string required
      The GitHub login associated with the organization.
    • ↳ avatarUrl string required
      The URL of the organization’s avatar image.
    • ↳ email string optional
      IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.
    • identities array[string] required
      Identities is the array of identities a Pulumi user’s account is tied to.
    • siteAdmin boolean optional
      SiteAdministrator is whether or not the user is a site administrator.
    • registryAdmin boolean optional
      RegistryAdmin is whether or not the user is a registry administrator.
    • tokenInfo TokenInfo optional
      TokenInfo is contains metadata, set only for machine tokens & to be used only in the CLI
    • ↳ name string required
      The name of the access token.
    • ↳ organization string required
      The organization the token is scoped to, if any.
    • ↳ team string required
      The team the token is scoped to, if any.
    • hasMFA boolean required
      Whether the user has multi-factor authentication enabled.
    • isOrgManaged boolean required
      Whether the user’s account is managed by an organization.
    • isManagedByMultiOrg boolean required
      Whether the user’s account is managed by multiple organizations.
    Errors: 400 invalid query parameter

    Get User Has Verified Email

    ▼
    GET /api/user/verified-email

    GetUserHasVerifiedEmail returns a success response if the user has a verified email, 404 not found if they are not verified

    Responses

    200 OK