Full Reference Docs - PropelAuth Docs

InfoThis documentation is just forPropelAuth Components, an optional library for those who want deeper design control over their UIs. Click here to view our standard documentation

Close banner

Full Reference Documentation

createOrg

Creates a new org and automatically adds the logged in user to it.

Arguments

Success Response

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { createOrg } = useAuthFrontendApis()

const response = await createOrg({
    name: 'Acme Inc',
    allow_users_to_join_by_domain: true,
    restrict_invites_by_domain: true,
})
response.handle({
    success(data) {
        console.log(data)
    },
    cannotCreateOrgs(error) {
        console.log('Cannot create orgs', error.user_facing_error)
    },
    cannotUsePersonalDomain(error) {
        console.log('Cannot use personal domain', error.user_facing_error)
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    userAlreadyInTooManyOrgs(error) {
        console.log('User already in too many orgs', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.log('Unexpected or unhandled error', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "org_id": "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    "first_org": true
}

CopyCopied!

createOrgApiKey

Creates an Org API key for the provided organization.

Arguments

Success Response

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { createOrgApiKey } = useAuthFrontendApis()

const response = await createOrgApiKey(orgId, 'Never', 'My API Key')
await response.handle({
    success: async () => {
        console.log('success')
    },
    invalidExpirationOption(error) {
        console.error('Invalid expiration option', error.user_facing_error)
    },
    noOrgApiKeyPermission(error) {
        console.error('Forbidden', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error.user_facing_error)
    },
    badRequest(error) {
        console.error(error.user_facing_errors.display_name)
    },
})

CopyCopied!

Successful Response

{
    "api_key_id": "justAnId",
    "api_key_token": "dhopw42..."
}

CopyCopied!

createPersonalApiKey

Creates a Personal API key for the logged in user.

Arguments

Success Response

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { createPersonalApiKey } = useAuthFrontendApis()

const response = await createPersonalApiKey('Never', 'My API Key')
await response.handle({
    success: async () => {
        console.log('success')
    },
    invalidExpirationOption(error) {
        console.error('Invalid expiration option', error.user_facing_error)
    },
    noPersonalApiKeyPermission(error) {
        console.error('Forbidden', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error.user_facing_error)
    },
    badRequest(error) {
        console.error(error.user_facing_errors.display_name)
    },
})

CopyCopied!

Successful Response

{
    "api_key_id": "justAnId",
    "api_key_token": "dhopw42..."
}

CopyCopied!

deleteAccount

Deletes the logged in user's account from your application.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { deleteAccount } = useAuthFrontendApis()

const response = await deleteAccount()
await response.handle({
    success: async () => {
        console.log('Account deleted')
    },
    actionDisabled(error) {
        console.log('Cannot delete account', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.log('Unexpected or unhandled error', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

deleteApiKey

Deletes the provided API Key.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { deleteApiKey } = useAuthFrontendApis()

const response = await deleteApiKey("justAnId")
await response.handle({
    success: async () => {
        console.log('success')
    },
    apiKeyNotFound(error) {
        console.error('API key not found', error.user_facing_error)
    },
    noApiKeyPermission(error) {
        console.error('Forbidden', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

deleteOrg

Deletes the provided organization.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { deleteOrg } = useAuthFrontendApis()

const response = await deleteOrg('1189c444-8a2d-4c41-8b4b-ae43ce79a492')
response.handle({
    success() {
        console.log('Org deleted')
    },
    orgNotFound(error) {
        console.log('Org not found', error.user_facing_error)
    },
    actionDisabled(error) {
        console.log('Cannot delete org', error.user_facing_error)
    },
    noDeletePermission(error) {
        console.log('No delete permission', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.log('Unexpected or unhandled error', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

disableMfa

Disables MFA for the logged in user.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { disableMfa } = useAuthFrontendApis()

const response = await disableMfa()
await response.handle({
    success: async () => {
        console.log('MFA successfully disabled.')
    },
    alreadyDisabled: () => {
        console.log('MFA is already disabled.')
    },
    unexpectedOrUnhandled() {
        console.error('An unexpected error occurred')
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

emailPasswordLogin

Accepts a user's email and password to log them in.

Arguments

Success Response

Returns one of the following:

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { emailPasswordLogin } = useAuthFrontendApis()

const response = await emailPasswordLogin({
    email: "test@example.com",
    password: "password"
})
response.handle({
    success(data) {
        // handle login state
    },
    passwordLoginDisabled(error) {
        console.error('Password login disabled', error)
    },
    userAccountDisabled(error) {
        console.error('User account disabled', error)
    },
    userAccountLocked(error) {
        console.error('User account locked', error)
    },
    invalidCredentials(error) {
        console.error('Invalid credentials', error)
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "login_state": "Finished"
}

CopyCopied!

enableMfa

Accepts the code provided by your authenticated user when setting up MFA. To set up MFA, use the QR Code (or secret) provided by fetchMfaStatusWithNewSecret.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { enableMfa } = useAuthFrontendApis()

const response = await enableMfa({ code: '123456' })
await response.handle({
    success: () => {
        console.log('MFA enabled')
    },
    badRequest: (error) => {
        console.log('Bad request error:', error.user_facing_errors.code)
    },
    unexpectedOrUnhandled: () => {
        console.log('An unexpected error occurred')
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

fetchExpiredInvites

Fetches a paginated list of an org's expired invites.

Arguments

Success Response

An array of expired invites for the provided org.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { fetchExpiredInvites } = useAuthFrontendApis()

const response = await fetchExpiredInvites("1189c444-8a2d-4c41-8b4b-ae43ce79a492", {
    page_number: 0,
    page_size: 10,
    email_search: "Acme",
});
await response.handle({
    success: (data) => {
        setResponse(data);
    },
    orgNotFound(error) {
        console.error('Org not found', error);
    },
    orgsNotEnabled(error) {
        console.error('Org not enabled', error);
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error);
    },
});

CopyCopied!

Successful Response

{
    "expired_invites": [\
        {\
            "email": "test@example.com",\
            "role": "Admin",\
            "additional_roles" : [\
                "Member"\
            ],\
            "expired_at_seconds": 1737217437\
        }\
    ],
    "total_count": 1,
    "page_number": 0,
    "page_size": 10,
    "has_more_results": false
}

CopyCopied!

fetchJoinableOrgs

Returns an array of organizations that the user can join based on their email domain.

Success Response

An array of objects that include the following:

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { fetchJoinableOrgs } = useAuthFrontendApis()

const response = await fetchJoinableOrgs()
response.handle({
    success(data) {
        console.log(data.orgs)
    },
    orgsNotEnabled(error) {
        console.error('Organizations are disabled', error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "orgs": [\
        {\
            "id": "org_123",\
            "name": "Acme Corp"\
        },\
        {\
            "id": "org_456",\
            "name": "Widget Co"\
        }\
    ]
}

CopyCopied!

fetchLoginState

Fetches the user's current login state, informing you of whether the user is logged in, needs to enroll in MFA, and more.

Success Response

Returns one of the following:

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { fetchLoginState } = useAuthFrontendApis()

const response = await fetchLoginState()
await response.handle({
    success: (data) => {
        // handle user based on data.login_state
    },
    unexpectedOrUnhandled() {
        console.log('An unexpected error occurred.')
    },
})

CopyCopied!

Successful Response

{
    "login_state": "LoginRequired"
}

CopyCopied!

fetchMfaStatusWithNewSecret

Fetches the current user's MFA status. If they do not have MFA enabled, it will provide you with a QR code to help get your user enrolled.

Success Response

The type of response depending on if the user has MFA enabled or disabled. Returns either Disabled or Enabled.

Returns true if the current user has MFA enabled. Otherwise, returns false.

Only returned if mfa_enabled equals true. Returns the current users MFA backup codes.

Only returned if mfa_enabled equals false.

Only returned if mfa_enabled equals false. The QR code the current user can scan to enable MFA.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { fetchMfaStatusWithNewSecret } = useAuthFrontendApis()

const response = await fetchMfaStatusWithNewSecret()
await response.handle({
    success: (data) => {
        if (data.mfa_enabled) {
            console.log('MFA is enabled')
            console.log('Backup codes: ', data.backup_codes)
        } else {
            console.log('MFA is disabled')
            console.log('QR code to enable it: ', data.new_qr)
            console.log('Secret to enable it: ', data.new_secret)
        }
    },
    unexpectedOrUnhandled: (error) => {
        console.error(error)
    },
})

CopyCopied!

Successful Response

// if MFA disabled
{
    "type": "Disabled",
    "mfa_enabled": false,
    "new_secret": "2CPN3MORX7...",
    "new_qr": "iVBORw0KGgoAAAA...",
    "has_password": true
}
// if MFA enabled
{
    "type": "Enabled",
    "mfa_enabled": true,
    "backup_codes": [\
    "6GD3YU5AQE",\
    "P5NQ28DWR",\
    "ICQ036M4L8"\
    ],
    "has_password": true
}

CopyCopied!

fetchOrgApiKeys

Fetches a paginated list of an org's API keys. This will not return the full API key, just the Key ID, expiration, created at, and metadata.

Arguments

Success Response

An array of API Keys belonging to the provided org.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { fetchOrgApiKeys } = useAuthFrontendApis()

const response = await fetchOrgApiKeys({
    org_id: '1189c444-8a2d-4c41-8b4b-ae43ce79a492',
    page_number: 0,
    page_size: 10,
    api_key_search: '31c41c16-c2...',
})
await response.handle({
    success: (data) => {
        console.log(data)
    },
    orgApiKeysDisabled(error) {
        console.error('Org API keys are disabled', error.user_facing_error)
    },
    orgNotFound(error) {
        console.error('Org not found', error.user_facing_error)
    },
    cannotAccessOrgApiKeys(error) {
        console.error('Cannot access org API keys', error.user_facing_error)
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "api_keys": [\
    {\
        "display_name": "My API Key",\
        "api_key_id": "eeb1dfea92cadc475dfce6d93aeac567",\
        "created_at": 1732639470,\
        "expires_at_seconds": 1732645813,\
        "metadata": null\
    },\
    {\
        "api_key_id": "e51c60d190d85d196c07c0caa44389c4",\
        "created_at": 1731707412,\
        "expires_at_seconds": null,\
        "metadata": {\
            "example": "test"\
        }\
    }\
    ],
    "total_api_keys": 2,
    "current_page": 0,
    "page_size": 10,
    "has_more_results": false
}

CopyCopied!

fetchOrgMembers

Fetches a paginated list of an org's members.

Arguments

Success Response

An array of API Keys belonging to the provided org.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { fetchOrgMembers } = useAuthFrontendApis()

const response = await fetchOrgMembers('1189c444-8a2d-4c41-8b4b-ae43ce79a492', {
    page_number: 0,
    page_size: 10,
    email_search: "test@example.com",
});
await response.handle({
    success: (data) => {
        console.log(data)
    },
    orgNotFound(error) {
        console.error('Org not found', error);
    },
    orgsNotEnabled(error) {
        console.error('Org not enabled', error);
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error);
    },
});

CopyCopied!

Successful Response

{
    "users": [\
        {\
            "user_id": "1d31f06...",\
            "email": "test@example.com",\
            "role": "Owner",\
            "additional_roles": [],\
            "possible_roles": [\
                "Owner",\
                "Admin",\
                "Member"\
            ],\
            "can_be_deleted": true,\
            "is_enabled": true,\
            "is_2fa_enabled": true\
        },\
        {\
            "user_id": "d20605...",\
            "email": "test2@example.com",\
            "role": "Admin",\
            "additional_roles": [],\
            "possible_roles": [\
                "Owner",\
                "Admin",\
                "Member"\
            ],\
            "can_be_deleted": true,\
            "is_enabled": true,\
            "is_2fa_enabled": false\
        }\
    ],
    "total_count": 2,
    "page_number": 0,
    "page_size": 10,
    "has_more_results": false
}

CopyCopied!

fetchOrgSettings

Fetches the provided org's settings and information, such as org name, SAML status, 2FA requirements, and more.

Arguments

Success Response

Returns true if the org can set up SAML.

Returns true if the org has SAML enabled.

Returns true if the org has SAML in test mode.

Returns true if the org can set up SCIM.

Returns true if the org can set has SCIM enabled.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { fetchOrgSettings } = useAuthFrontendApis()

const response = await fetchOrgSettings('1189c444-8a2d-4c41-8b4b-ae43ce79a492')
await response.handle({
    success: (data) => {
        console.log(data)
    },
    orgsNotEnabled() {
        console.log('Organizations are not enabled.')
    },
    orgNotFound() {
        console.log('Organization not found.')
    },
    forbidden() {
        console.log("You do not have permission to view this organization's settings.")
    },
    unexpectedOrUnhandled() {
        console.log('An unexpected error occurred.')
    },
})

CopyCopied!

Successful Response

{
    "user_can_update_metadata": true,
    "user_can_edit_org_access": true,
    "org_name": "Acme Inc",
    "autojoin_by_domain": true,
    "restrict_to_domain": true,
    "existing_domain": "acmeinc.com",
    "current_user_domain": "acmeinc.com",
    "current_user_domain_is_personal": false,
    "require_2fa_by": "1732645813",
    "can_setup_saml": true,
    "is_saml_enabled": false,
    "is_saml_in_test_mode": false,
    "can_setup_scim": false,
    "is_scim_enabled": false
}

CopyCopied!

fetchPendingOrgInvites

Fetches a paginated list of an org's invites.

Arguments

Success Response

An array of invites for the provided org.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { fetchPendingOrgInvites } = useAuthFrontendApis()

const response = await fetchPendingOrgInvites("1189c444-8a2d-4c41-8b4b-ae43ce79a492", {
    page_number: 0,
    page_size: 10,
    email_search: "test@test.com",
});
await response.handle({
    success: (data) => {
        console.log("success")
    },
    orgNotFound(error) {
        console.error('Org not found', error);
    },
    orgsNotEnabled(error) {
        console.error('Org not enabled', error);
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error);
    },
});

CopyCopied!

Successful Response

{
    "pending_invites": [\
        {\
            "email": "test@example.com",\
            "role": "Admin",\
            "additional_roles": [],\
            "expires_at_seconds": 1737217437\
        }\
    ],
    "total_count": 1,
    "page_number": 0,
    "page_size": 10,
    "has_more_results": false
}

CopyCopied!

fetchPersonalApiKeys

Fetches a paginated list of the user's API keys. This will not return the full API key, just the Key ID, expiration, created at, and metadata.

Arguments

Success Response

An array of API Keys belonging to the logged in user.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { fetchPersonalApiKeys } = useAuthFrontendApis()

const response = await fetchPersonalApiKeys({
    page_number: 0,
    page_size: 10,
    api_key_search: '1189c444-8a...',
})
await response.handle({
    success: (data) => {
        console.log(data)
    },
    personalApiKeysDisabled(error) {
        console.error('Personal API keys are disabled', error.user_facing_error)
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "api_keys": [\
        {\
            "display_name": "My API Key",\
            "api_key_id": "26bafab...",\
            "created_at": 1736553453,\
            "expires_at_seconds": 1737763053,\
            "metadata": null\
        },\
        {\
            "api_key_id": "df71d4e1...",\
            "created_at": 1736553453,\
            "expires_at_seconds": 1737763053,\
            "metadata": {\
                "test": "example"\
            }\
        }\
    ],
    "total_api_keys": 2,
    "current_page": 0,
    "page_size": 10,
    "has_more_results": false
}

CopyCopied!

inviteUserToOrg

Sends an invitation to a user to join an organization.

Arguments

If using multiple roles per user, an array of additional roles for the user.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { inviteUserToOrg } = useAuthFrontendApis()

const response = await inviteUserToOrg({
    org_id: '1189c444-8a2d-4c41-8b4b-ae43ce79a492',
    email: 'test@example.com',
    role: 'Admin',
    // if using multi-role support
    additional_roles: [\
        "Member"\
    ]
})
response.handle({
    success: () => {
        console.log('User invited')
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    noInvitePermission(error) {
        console.error('No invite permission', error)
    },
    orgNotFound(error) {
        console.error('Org not found', error)
    },
    orgsNotEnabled(error) {
        console.error('Org not enabled', error)
    },
    userAlreadyInOrg(error) {
        console.error('User already in org', error)
    },
    orgMaxUsersLimitExceeded(error) {
        console.error('Org max users limit exceeded', error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

joinOrg

Adds the logged in user as a member of the provided organization.

Arguments

Success Response

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { joinOrg } = useAuthFrontendApis()

const response = await joinOrg("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
response.handle({
    success(data) {
        console.log("User added to org: ", data.org_id)
    },
    orgNotFound(error) {
        console.error('Org not found', error)
    },
    orgsNotEnabled(error) {
        console.error('Org not enabled', error)
    },
    userAlreadyInTooManyOrgs(error) {
        console.error('User already in too many orgs', error)
    },
    orgMaxUsersLimitExceeded(error) {
        console.error('Org max users limit exceeded', error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error)
    },
})

CopyCopied!

Successful Response

{
    "org_id": "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    "first_org": true
}

CopyCopied!

loginViaSamlForOrg

Accepts either a domain, email, or org_id and returns a Enterprise SSO login URL for the specified organization. Works with both OIDC and SAML login.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { loginViaSamlForOrg } = useAuthFrontendApis()

const response = await loginViaSamlForOrg({
    // only one of these is required
    email: "test@example.com",
    domain: "acme.com",
    org_id: "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
})
response.handle({
    success(data) {
        // redirect to data.login_url
    },
    orgNotFound(error) {
        console.error('Org not found', error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "login_url": "https://example.com/saml/login"
}

CopyCopied!

loginWithSocialProvider

Redirects the user to login with the specified Social Login provider. If signups are enabled, will create a new user if one does not already exist.

Arguments

The provider to login with. Must be one of these options:

Request

import { SocialLoginProvider } from '@propelauth/frontend-apis'
const { loginWithSocialProvider } = useAuthFrontendApis()

// Typescript version
<button onClick={() => loginWithSocialProvider(SocialLoginProvider.GITHUB)}>
    Login with Github
</button>

// Javascript version
<button onClick={() => loginWithSocialProvider("Google")}>
    Login with Google
</button>

CopyCopied!

passwordlessLogin

Sends a magic link to the user's email address to log them in.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { passwordlessLogin } = useAuthFrontendApis()

const response = await passwordlessLogin({
    email: "test@example.com",
    create_if_doesnt_exist: false
})
response.handle({
    success() {
        console.log('Magic link sent')
    },
    userAccountDisabled(error) {
        console.error('User account disabled', error.user_facing_error)
    },
    userAccountLocked(error) {
        console.error('User account locked', error.user_facing_error)
    },
    passwordlessLoginDisabled(error) {
        console.error('Passwordless login disabled', error.user_facing_error)
    },
    cannotSignupWithPersonalEmail(error) {
        console.error('Cannot signup with personal email', error.user_facing_error)
    },
    domainNotAllowed(error) {
        console.error('Domain not allowed', error.user_facing_error)
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

removeUserFromOrg

Removes the provided user from the provided organization.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { removeUserFromOrg } = useAuthFrontendApis()

const response = await removeUserFromOrg({
    org_id: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    user_id: "31c41c16-c281-44ae-9602-8a047e3bf33d",
});
await response.handle({
    success: async () => {
        console.log('success')
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    orgNotFound(error) {
        console.error('Org not found', error);
    },
    userNotFoundInOrg(error) {
        console.error('User not found', error);
    },
    noRemovePermission(error) {
        console.error('No remove permission', error);
    },
    orgsNotEnabled(error) {
        console.error('Org not enabled', error);
    },
    mustBeAtLeastOneOwner(error) {
        console.error('There must be at least one user with the Owner role in this org', error);
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error);
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

resendEmailConfirmation

Sends another confirmation email to the logged in user.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { resendEmailConfirmation } = useAuthFrontendApis()

const response = await resendEmailConfirmation()
response.handle({
    success() {
        console.log('Confirmation email resent')
    },
    rateLimited(error) {
        console.error('Rate limited', error.user_facing_error)
    },
    emailAlreadyConfirmed(error) {
        console.error('Email already confirmed', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

revokeUserOrgInvitation

Revokes an existing invitation to a user to join an organization.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { revokeUserOrgInvitation } = useAuthFrontendApis()

const response = await revokeUserOrgInvitation({
    org_id: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    email: "test@test.com",
});
await response.handle({
    async success() {
        console.log("success")
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    orgNotFound(error) {
        console.error('Org not found', error);
    },
    orgsNotEnabled(error) {
        console.error('Org not enabled', error);
    },
    noRevokeInvitePermission(error) {
        console.error('No revoke invite permission', error);
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error);
    },
});

CopyCopied!

Successful Response

{}

CopyCopied!

sendForgotPasswordEmail

Sends the user an email to reset their password if an account with that email exists.

Arguments

Success Response

A dictionary of sniper links you can provide to the user for gmail, outlook, and yahoo.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { sendForgotPasswordEmail } = useAuthFrontendApis()

const response = await sendForgotPasswordEmail({
    email: "test@example.com"
})
response.handle({
    success(data) {
        console.log(data)
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "message": "If that email address is in our database, we will send you an email to reset your password.",
    "sniper_links": {
        "gmail": "https://mail.google.com/mail/u/0/#search/propelauth",
        "outlook": "https://outlook.live.com/mail/0/inbox",
        "yahoo": "https://mail.yahoo.com/d/folders/1"
    }
}

CopyCopied!

signup

Create a user for your application using email and password. See passwordlesslogin and loginWithSocialProvider for alternative ways to sign users up.

Arguments

The username of the user to create. See User Properties for more information.

The first name of the user to create. See User Properties for more information.

The last name of the user to create. See User Properties for more information.

A dictionary of custom properties of the user to create. See Custom User Properties for more information.

The token included as a invite_token URL parameter in the invite link sent to the invited user.

The token returned by the Turnstile widget. Required if using the PropelAuth Cloudflare Turnstile Integration.

Success Response

Returns one of the following:

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { signup } = useAuthFrontendApis()

const response = await signup({
    email: "test@example.com",
    password: "password",
    username: "airbud3",
    first_name: "Buddy",
    last_name: "Framm",
    properties: {
        favoriteSport: "Basketball"
    },
    invite_token: "eyJvcmdfaWQ...",
    turnstile_token: "0.sSXqFt-EH..Z"
})
response.handle({
    success(data) {
        // handle login state
    },
    signupDisabled(error) {
        console.error('Signups are disabled', error)
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "login_state": "Finished",
    "user_id": "bf186f61-b204-4dd6-a6dc-a4ba2c97db1d"
}

CopyCopied!

updateApiKey

Updates the display name of an API Key.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { updateApiKey } = useAuthFrontendApis()

const response = await updateApiKey({
    api_key_id: 'c45ccb5055080ad0ebb03d43e6332f5d',
    display_name: 'My API Key',
})
response.handle({
    success: async () => {
        console.log('success')
    },
    apiKeyNotFound(error) {
        console.error('API key not found', error.user_facing_error)
    },
    noApiKeyPermission(error) {
        console.error('Forbidden', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error.user_facing_error)
    },
    badRequest(error) {
        console.error(error.user_facing_errors.display_name)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

updateEmail

Starts the update email flow by sending a confirmation email to the user. If the user accepts, their email will be updated.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { updateEmail } = useAuthFrontendApis()

const response = await updateEmail({
    new_email: 'test@example.com',
    password: 'password',
})
response.handle({
    success: () => {
        console.log('Email update confirmation sent successfully')
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    failedToSendEmail: (error) => {
        console.log('Failed to send email', error.user_facing_error)
    },
    incorrectPassword: (error) => {
        console.log('The user provided an incorrect password', error.user_facing_error)
    },
    userAccountLocked: (error) => {
        console.log('User account locked', error.user_facing_error)
    },
    rateLimit: (error) => {
        console.log('Rate limit error', error.user_facing_error)
    },
    emailChangeDisabled: (error) => {
        console.error('Email change disabled', error.user_facing_error)
    },
    cannotChangeEmailDueToOrgMembership: (error) => {
        console.log('Cannot change email due to org membership', error.user_facing_error)
    },
    unexpectedOrUnhandled(error) {
        console.log('Unexpected or unhandled error', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

updateOrgSettings

Updates the settings for an organization.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { updateOrgSettings } = useAuthFrontendApis()

const response = await updateOrgSettings({
    org_id: '1189c444-8a2d-4c41-8b4b-ae43ce79a492',
    name: 'Acme Inc',
    allow_users_to_join_by_domain: true,
    restrict_invites_by_domain: true,
    require_2fa_by: '2025-01-16T00:00:00.000Z',
})
response.handle({
    success() {
        console.log('Updated org settings successfully.')
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    orgsNotEnabled(error) {
        console.log('Org not enabled', error)
    },
    orgNotFound(error) {
        console.log('Org not found', error)
    },
    forbidden(error) {
        console.log('Forbidden', error)
    },
    unexpectedOrUnhandled(error) {
        console.log('Unexpected or unhandled error', error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

updatePassword

Updates the logged in user's password.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { updatePassword } = useAuthFrontendApis()

const response = await updatePassword({
    current_password: 'currentPassword',
    password: 'newPassword',
})
response.handle({
    success: () => {
        console.log('Password updated')
    },
    incorrectPassword(error) {
        console.log('Incorrect password', error.user_facing_error)
    },
    userAccountLocked(error) {
        setGlobalError('User Account is locked', error.user_facing_error)
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

updateUserMetadata

Updates user property fields such as username, first_name, last_name, and any custom user properties.

Arguments

An object containing any custom user properties.

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { updateUserMetadata } = useAuthFrontendApis()

const response = await updateUserMetadata({
    username: 'airbud3',
    first_name: 'Buddy',
    last_name: 'Framm',
    properties: {
        favorite_sport: 'basketball',
    },
})
await response.handle({
    success: () => {
        console.log('Updated user properties successfully.')
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{}

CopyCopied!

updateUserRoleInOrg

Updates the provided user's role within the provided organization.

Arguments

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { updateUserRoleInOrg } = useAuthFrontendApis()

const response = await updateUserRoleInOrg({
    org_id: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    user_id: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    role: "Admin",
    // if using multi-role support
    additional_roles: [\
        "Member"\
    ]
});
await response.handle({
    success: async () => {
        console.log('success')
    },
    badRequest(error) {
        for (const [field, fieldErrorMessage] of Object.entries(error.user_facing_errors)) {
            console.log('Error: "' + fieldErrorMessage + '" for field: "' + field + '"')
        }
    },
    userNotFoundInOrg(error) {
        console.error('User not found', error);
    },
    noUpdateRolePermission(error) {
        console.error('No update role permission', error);
    },
    orgsNotEnabled(error) {
        console.error('Org not enabled', error);
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error);
    },
});

CopyCopied!

Successful Response

{}

CopyCopied!

verifyMfaBackupCodeForLogin

Verifies the user's MFA code for login.

Arguments

Success Response

Returns one of the following:

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { verifyMfaBackupCodeForLogin } = useAuthFrontendApis()

const response = await verifyMfaBackupCodeForLogin({
    code: "123456",
})
response.handle({
    success() {
        // handle login state
    },
    invalidCode(error) {
        console.error('Invalid code provided', error)
    },
    userAccountDisabled(error) {
        console.error('User account disabled', error)
    },
    userAccountLocked(error) {
        console.error('User account locked', error)
    },
    mfaCookieTimeout(error) {
        console.error('Session timeout', error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "login_state": "Finished"
}

CopyCopied!

verifyMfaForLogin

Verifies the user's MFA code for login.

Arguments

Success Response

Returns one of the following:

Response Functions

The response object has a handle function that you can use to handle the response. These functions can be async, and you can return values from them.

Request

const { verifyMfaForLogin } = useAuthFrontendApis()

const response = await verifyMfaForLogin({
    code: "123456",
})
response.handle({
    success() {
        // handle login state
    },
    userAccountDisabled(error) {
        console.error('User account disabled', error)
    },
    userAccountLocked(error) {
        console.error('User account locked', error)
    },
    mfaCookieTimeout(error) {
        console.error('Session timeout', error)
    },
    badRequest(error) {
        console.error('Bad request', error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

CopyCopied!

Successful Response

{
    "login_state": "Finished"
}

CopyCopied!