Logo
Frontend
Backend 

User API Reference

These APIs can be called from the backend using your PropelAuth API Key.

POST/api/backend/v1/user/

Create User

Creates a new user

Properties

  • Name
    email *
    Type
    string
    Description
    The user's email address
  • Name
    emailConfirmed
    Type
    boolean
    Description
    Whether the user's email address has been confirmed. Default is false.
  • Name
    sendEmailToConfirmEmailAddress
    Type
    boolean
    Description
    Whether to send an email to confirm the email address. Default is false.
  • Name
    password
    Type
    string
    Description
    The user's password. If you provide this, make sure to send it to the user so they can log in.
  • Name
    askUserToUpdatePasswordOnLogin
    Type
    boolean
    Description
    If true, the user will be prompted to set/update their password when they next log in. Default is false.
  • Name
    username
    Type
    string
    Description
    The user's username
  • Name
    firstName
    Type
    string
    Description
    The user's first name
  • Name
    lastName
    Type
    string
    Description
    The user's last name
  • Name
    properties
    Type
    { [key: string]: any }
    Description
    A dictionary of custom properties for the user. See Custom Properties for more details.

Request

auth.createUser({
    email: "test@example.com",
    emailConfirmed: false,
    sendEmailToConfirmEmailAddress: false,
    
    password: "hxjV6A0zcp",
    askUserToUpdatePasswordOnLogin: false,
    
    username: "airbud3",
    firstName: "Buddy",
    lastName: "Framm",
    properties: {
        favoriteSport: "basketball",
    }
})

Successful Response

{ 
    userId: "bf186f61-b204-4dd6-a6dc-a4ba2c97db1d"
}
GET/api/backend/v1/user/<userId>

Fetch User

Fetches a user. You can find the user by their ID, email address, or username (if you have usernames enabled).

Properties

  • Name
    userId *
    Type
    string
    Description
    The user's ID

Request

auth.fetchUserMetadataByUserId(
    "31c41c16-c281-44ae-9602-8a047e3bf33d",
    true, // includeOrgs
)

Successful Response

{ 
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    email: "test@example.com",
    emailConfirmed: true,
    username: "airbud3",
    firstName: "Buddy",
    lastName: "Framm",
    pictureUrl: "https://example.com/picture.jpg",
    properties: {
        favoriteSport: "basketball"
    },
    hasPassword: true,
    updatePasswordRequired: false,
    locked: false,
    enabled: true,
    mfaEnabled: false,
    canCreateOrgs: true,
    createdAt: 1627600000,
    lastActiveAt: 1627600000,
    orgIdToOrgInfo: {
        "1189c444-8a2d-4c41-8b4b-ae43ce79a492": {
            orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
            orgName: "Example Org",
            orgMetadata: {
                timezone: "EST",
            },
            urlSafeOrgName: "example-org",
            inheritedUserRolesPlusCurrentRole: [
                "Admin",
                "Owner",
                "Member"
            ],
            userRole: "Owner",
            userPermissions: ["can_view_billing"],
            orgRoleStructure: "single_role_in_hierarchy",
            additionalRoles: []
        }
    },
    legacyUserId: "1234567890"
}
GET/api/backend/v1/user/query

Query for Users

Paginates through the list of users. You can also filter the list by a partial email/username match, and sort the list by different fields.

Properties

  • Name
    pageSize *
    Type
    number
    Description
    The number of users to return per page
  • Name
    pageNumber *
    Type
    number
    Description
    The page number to return
  • Name
    orderBy
    Type
    string
    Description
    One of CREATED_AT_ASC, CREATED_AT_DESC, LAST_ACTIVE_AT_ASC, LAST_ACTIVE_AT_DESC, EMAIL, or USERNAME.
  • Name
    emailOrUsername
    Type
    string
    Description
    A partial email or username to filter the list by
  • Name
    includeOrgs
    Type
    boolean
    Description
    Whether to include the user’s orgs in the response

Request

auth.fetchUsersByQuery({
    emailOrUsername: "test",
    includeOrgs: true,
    orderBy: "CREATED_AT_DESC",
    pageNumber: 0,
    pageSize: 10,
})

Successful Response

{
    totalUsers: 3,
    currentPage: 0,
    pageSize: 10,
    hasMoreResults: false,
    users: [{
        userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
        // ... see fetch user for full schema
    }]
}
PUT/api/backend/v1/user/<userId>

Update User

Properties

  • Name
    userId *
    Type
    string
    Description
    The ID of the user to update
  • Name
    username
    Type
    string
    Description
    The user's username
  • Name
    firstName
    Type
    string
    Description
    The user's first name
  • Name
    lastName
    Type
    string
    Description
    The user's last name
  • Name
    pictureUrl
    Type
    string
    Description
    The user's profile picture URL. You can manage this yourself or use our account pages which allow the user to upload a picture that we host.
  • Name
    properties
    Type
    { [key: string]: any }
    Description
    A dictionary of custom properties for the user. See Custom Properties for more details.
  • Name
    updatePasswordRequired
    Type
    boolean
    Description
    If true, the user will be prompted to set/update their password when they next log in. Default is false.

Request

auth.updateUserMetadata(
    "31c41c16-c281-44ae-9602-8a047e3bf33d", 
    {
        username: "username",
        firstName: "firstName",
        lastName: "lastName",
        pictureUrl: "https://example.com/img.png",
        properties: {
            "customProperty": "value"
        },
        updatePasswordRequired: false,
    }
)

Successful Response

true
PUT/api/backend/v1/user/<userId>/email

Update User Email

Updates a user's email address. You can choose whether to update it immediately or send an email to confirm the new email address.

Properties

  • Name
    userId *
    Type
    string
    Description
    The ID of the user to update
  • Name
    newEmail *
    Type
    string
    Description
    The user's new email address
  • Name
    requireEmailConfirmation *
    Type
    boolean
    Description
    Whether the new email address requires confirmation. If true, an email will be sent to the new email address to confirm. If false, the users email address will be updated and confirmed immediately.

Request

auth.updateUserEmail(
    "31c41c16-c281-44ae-9602-8a047e3bf33d", // userId
    {
        newEmail: "test@example.com",
        requireEmailConfirmation: false,
    }
)

Successful Response

{}
PUT/api/backend/v1/user/<userId>/password

Update User Password

Updates a user's password. You can optionally require the user to update their password on their next login.

Properties

  • Name
    userId *
    Type
    string
    Description
    The ID of the user to update
  • Name
    password *
    Type
    string
    Description
    The user's new password
  • Name
    askUserToUpdatePasswordOnLogin
    Type
    boolean
    Description
    Whether to ask the user to update their password on their next login

Request

auth.updateUserPassword("31c41c16-c281-44ae-9602-8a047e3bf33d", {
    password: "moresecurethanthis",
    askUserToUpdatePasswordOnLogin: false 
});

Successful Response

true
POST/api/backend/v1/magic_link

Create Magic Link

Creates a magic link that a user can use to log in. You can customize the expiration and the location the user is redirected to after logging in. Note that this doesn't send the email to the user, it just generates it and returns the URL.

Properties

  • Name
    email *
    Type
    string
    Description
    The user's email address
  • Name
    redirectToUrl
    Type
    string
    Description
    The URL to redirect the user to after they've logged in
  • Name
    expiresInHours
    Type
    number
    Description
    How many hours the link should be valid for
  • Name
    createNewUserIfOneDoesntExist
    Type
    boolean
    Description
    If true, when the user clicks the link, a new user will be created if one does not already exist

Request

auth.createMagicLink({
    email: "test@example.com",
    redirectToUrl: "https://app.example.com/custom_location",
    expiresInHours: 24,
    createNewUserIfOneDoesntExist: false,
});

Successful Response

{
    "url": "https://auth.yourdomain.com/U6FhAcghLw5XlHyzoyFA"
}
POST/api/backend/v1/access_token

Create Access Token

Generates an access token for a user. This can be used to test your backend without a frontend in tools like cURL or Postman. You can also choose the duration, which is useful for generating long-lived tokens for testing.

Properties

  • Name
    userId *
    Type
    string
    Description
    The user's ID
  • Name
    durationInMinutes *
    Type
    number
    Description
    How long the token should be valid for

Request

auth.createAccessToken({
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    durationInMinutes: 24 * 60,
});

Successful Response

{
    "accessToken": "eyJ0eXAiOi..."
}
POST/api/backend/v1/migrate_user/

Migrate User From External Source

Migrates a user from an external source. This is similar to the Create User API, but for cases where the user already exists in another system. With this API you can maintain the user's existing ID, password (via a hashed password), and 2FA.

Properties

  • Name
    email *
    Type
    string
    Description
    The user's email address
  • Name
    emailConfirmed *
    Type
    boolean
    Description
    Whether the user's email address has been confirmed. Default is false.
  • Name
    existingUserId
    Type
    string
    Description
    The user’s ID in the existing system. This ID will be stored on the user as a legacyUserId and it is present everywhere userId's are (e.g. fetching user metadata or validating a user's token).
  • Name
    existingPasswordHash
    Type
    string
    Description
    The user's hashed password. We support bcrypt, argon2, and pbkdf2_sha256 password hashes. If you use a different hash, please contact us.
  • Name
    existingMfaBase32EncodedSecret
    Type
    string
    Description
    The user's MFA secret, base32 encoded. If specified the user will have MFA enabled by default.
  • Name
    askUserToUpdatePasswordOnLogin
    Type
    boolean
    Description
    If true, the user will be prompted to set/update their password when they next log in. Default is false.
  • Name
    enabled
    Type
    boolean
    Description
    Whether the user is enabled. Default is true.
  • Name
    username
    Type
    string
    Description
    The user's username
  • Name
    firstName
    Type
    string
    Description
    The user's first name
  • Name
    lastName
    Type
    string
    Description
    The user's last name
  • Name
    properties
    Type
    { [key: string]: any }
    Description
    A dictionary of custom properties for the user. See Custom Properties for more details.

Request

auth.migrateUserFromExternalSource({
    email: "test@example.com",
    emailConfirmed: true,

    existingUserId: "1234",
    existingPasswordHash: "bcrypt_hash",
    existingMfaBase32EncodedSecret: "base32_encoded_secret",

    askUserToUpdatePasswordOnLogin: false,
    enabled: true,
    
    username: "airbud3",
    firstName: "Buddy",
    lastName: "Framm",
    properties: {
        "favoriteSport": "basketball",
    }
})

Successful Response

{ 
    userId: "bf186f61-b204-4dd6-a6dc-a4ba2c97db1d"
}
DELETE/api/backend/v1/user/<userId>

Delete User

Deletes a user. This will permanently delete the user and all of the user's data.

Properties

  • Name
    userId *
    Type
    string
    Description
    The user's ID

Request

auth.deleteUser("31c41c16-c281-44ae-9602-8a047e3bf33d")

Successful Response

true
POST/api/backend/v1/user/<userId>/disable

Disable / Block User

Disables / blocks a user. This will prevent the user from logging in until the user is disabled again.

Properties

  • Name
    userId *
    Type
    string
    Description
    The user's ID

Request

auth.disableUser("31c41c16-c281-44ae-9602-8a047e3bf33d")

Successful Response

true
POST/api/backend/v1/user/<userId>/enable

Enable / Unblock User

Enables / Unblocks a user that was previously disabled / blocked.

Properties

  • Name
    userId *
    Type
    string
    Description
    The user's ID

Request

auth.enableUser("31c41c16-c281-44ae-9602-8a047e3bf33d")

Successful Response

true
POST/api/backend/v1/user/<userId>/disable_2fa

Disable User 2FA

Disables two-factor authentication for a user.

Properties

  • Name
    userId *
    Type
    string
    Description
    The user's ID

Request

auth.disableUser2fa("31c41c16-c281-44ae-9602-8a047e3bf33d")

Successful Response

true