Full Reference Documentation

createOrg

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

Arguments

Name
name *
Type
string
Description
The name of the org to be created
Name
allow_users_to_join_by_domain *
Type
boolean
Description
If a domain is set for the org, allow users to the org if their domain matches the org's domain.
Name
restrict_invites_by_domain *
Type
boolean
Description
If a domain is set for the org, only allow users with that domain to join.

Success Response

Name
org_id
Type
string
Description
The ID of the new org.
Name
first_org
Type
boolean
Description
If the new org is the first org the user belongs to.

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.

Name
success
Description
Successful request.
Name
cannotCreateOrgs
Description
The user does not have permission to create orgs.
Name
cannotUsePersonalDomain
Description
The user provided a domain such as "gmail.com", "microsoft.com", etc.
Name
userAlreadyInTooManyOrgs
Description
User already belongs to the maximum amount of orgs.
Name
badRequest
Description
Incorrect arguments provided.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

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

createOrgApiKey

Creates an Org API key for the provided organization.

Arguments

Name
orgId *
Type
string
Description
The ID of the org to create an API key for
Name
expirationOption *
Type
string
Description
Can be one of the following: 'TwoWeeks' | 'OneMonth' | 'ThreeMonths' | 'SixMonths' | 'OneYear' | 'Never'

Success Response

Name
api_key_id
Type
string
Description
The ID of the API Key.
Name
api_key_token
Type
string
Description
The API Key.

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.

Name
success
Description
Successful request.
Name
invalidExpirationOption
Description
Incorrect argument provided for 'expirationOption'
Name
noOrgApiKeyPermission
Description
User does not have permission to create an org API key.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

Request

const { createOrgApiKey } = useAuthFrontendApis()

const response = await createOrgApiKey(orgId, 'Never')
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)
    },
})

Successful Response

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

createPersonalApiKey

Creates a Personal API key for the logged in user.

Arguments

Name
expirationOption *
Type
string
Description
Can be one of the following: 'TwoWeeks' | 'OneMonth' | 'ThreeMonths' | 'SixMonths' | 'OneYear' | 'Never'

Success Response

Name
api_key_id
Type
string
Description
The ID of the API Key.
Name
api_key_token
Type
string
Description
The API Key.

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.

Name
success
Description
Successful request.
Name
invalidExpirationOption
Description
Incorrect argument provided for 'expirationOption'
Name
noPersonalApiKeyPermission
Description
User does not have permission to create a personal API key.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

Request

const { createPersonalApiKey } = useAuthFrontendApis()

const response = await createPersonalApiKey('Never')
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)
    },
})

Successful Response

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

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.

Name
success
Description
Successful request.
Name
actionDisabled
Description
The 'Users can delete their own accounts' setting in your PropelAuth dashboard is disabled
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{}

deleteApiKey

Deletes the provided API Key.

Arguments

Name
apiKeyId *
Type
string
Description
The ID of the API Key to be deleted.

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.

Name
success
Description
Successful request.
Name
apiKeyNotFound
Description
API Key ID not associated with an API key that belongs to the user.
Name
noApiKeyPermission
Description
User does not have permission to delete the API key.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{}

deleteOrg

Deletes the provided organization.

Arguments

Name
orgId *
Type
string
Description
The ID of the org to be deleted.

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.

Name
success
Description
Successful request.
Name
orgNotFound
Description
The provided org does not exist.
Name
actionDisabled
Description
The 'Users can delete their own orgs' setting is disabled in your PropelAuth dashboard.
Name
noDeletePermission
Description
User does not have permission to delete the org.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{}

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.

Name
success
Description
Successful request.
Name
alreadyDisabled
Description
MFA not enabled for user.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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')
    },
})

Successful Response

{}

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

Arguments

Name
email *
Type
string
Description
The email of the user to log in.
Name
password *
Type
string
Description
The password of the user to log in.

Success Response

Name
login_state
Type
LoginState
Description
Returns one of the following:
- LOGIN_REQUIRED
- TWO_FACTOR_REQUIRED
- EMAIL_NOT_CONFIRMED_YET
- USER_MISSING_REQUIRED_PROPERTIES
- USER_MUST_BE_IN_AT_LEAST_ONE_ORG
- UPDATE_PASSWORD_REQUIRED
- TWO_FACTOR_ENROLLMENT_REQUIRED
- LOGGED_IN

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.

Name
success
Description
Successful request.
Name
passwordLoginDisabled
Description
Password login is disabled in the PropelAuth Dashboard.
Name
userAccountDisabled
Description
User cannot login due to their account being disabled.
Name
userAccountLocked
Description
User cannot login due to their account being locked.
Name
invalidCredentials
Description
The email or password provided is incorrect.
Name
badRequest
Description
Incorrect arguments provided.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{
    "login_state": "Finished"
}

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

Name
code *
Type
string
Description
The code generated by your user's authenticator.

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.

Name
success
Description
Successful request.
Name
alreadyEnabled
Description
User has MFA enabled already.
Name
badRequest
Description
Incorrect arguments provided. This is the error you will get if the code is incorrect.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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')
    },
})

Successful Response

{}

fetchExpiredInvites

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

Arguments

Name
orgId *
Type
string
Description
The ID of the org to fetch expired invites for.
Name
page_number
Type
number
Description
The page number to return. Starts at 0.
Name
page_size
Type
number
Description
The amount of results per page.
Name
email_search
Type
string
Description
Filter by invite email.

Success Response

Name
expired_invites
Type
ExpiredOrgInvite[]
Description
An array of expired invites for the provided org.
- email string
- role string
- additional_roles string[]
- expires_at_seconds number
Name
total_count
Type
number
Description
The total amount of expired org invites.
Name
page_number
Type
number
Description
The current page.
Name
page_size
Type
number
Description
The maximum amount of results of the page.
Name
has_more_results
Type
boolean
Description
Returns true of there are more results beyond the current page.

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.

Name
success
Description
Successful request.
Name
orgNotFound
Description
The provided Org ID was not found.
Name
orgsNotEnabled
Description
Organizations are not enabled for the project.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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);
    },
});

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
}

fetchJoinableOrgs

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

Success Response

Name
orgs
Type
JoinableOrg[]
Description
An array of objects that include the following:
- id: The ID of the organization.
- name: The name of the organization.

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.

Name
success
Description
Successful request.
Name
orgsNotEnabled
Description
Organizations are not enabled in the PropelAuth Dashboard.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

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

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

Name
login_state
Type
LoginState
Description
Returns one of the following:
- LOGIN_REQUIRED
- TWO_FACTOR_REQUIRED
- EMAIL_NOT_CONFIRMED_YET
- USER_MISSING_REQUIRED_PROPERTIES
- USER_MUST_BE_IN_AT_LEAST_ONE_ORG
- UPDATE_PASSWORD_REQUIRED
- TWO_FACTOR_ENROLLMENT_REQUIRED
- LOGGED_IN

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.

Name
success
Description
Successful request.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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.')
    },
})

Successful Response

{
    "login_state": "LoginRequired"
}

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

Name
type
Type
string
Description
The type of response depending on if the user has MFA enabled or disabled. Returns either Disabled or Enabled.
Name
mfa_enabled
Type
boolean
Description
Returns true if the current user has MFA enabled. Otherwise, returns false.
Name
backup_codes
Type
string[]
Description
Only returned if mfa_enabled equals true. Returns the current users MFA backup codes.
Name
new_secret
Type
string
Description
Only returned if mfa_enabled equals false.
Name
new_qr
Type
string
Description
Only returned if mfa_enabled equals false. The QR code the current user can scan to enable MFA.
Name
has_password
Type
boolean
Description
If the user has a password configured.

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.

Name
success
Description
Successful request.
Name
emailNotConfirmed
Description
User has not yet confirmed their email address.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

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
}

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

Name
org_id *
Type
string
Description
The ID of the org to fetch expired invites for.
Name
page_number
Type
number
Description
The page number to return. Starts at 0.
Name
page_size
Type
number
Description
The amount of results per page.
Name
api_key_search
Type
string
Description
Filter by Key ID.

Success Response

Name
api_keys
Type
OrgApiKey[]
Description
An array of API Keys belonging to the provided org.
- api_key_id string
- created_at number
- expires_at_seconds number | null
- metadata object | null
Name
total_api_keys
Type
number
Description
The total amount of API keys belonging to the org.
Name
current_page
Type
number
Description
The current page.
Name
page_size
Type
number
Description
The maximum amount of results of the page.
Name
has_more_results
Type
boolean
Description
Returns true of there are more results beyond the current page.

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.

Name
success
Description
Successful request.
Name
orgApiKeysDisabled
Description
Org API keys are not enabled in your PropelAuth project.
Name
badRequest
Description
Incorrect arguments provided.
Name
orgNotFound
Description
The provided Org ID was not found.
Name
cannotAccessOrgApiKeys
Description
The user does not have permission to access org API keys.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{
    "api_keys": [
    {
        "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
}

fetchOrgMembers

Fetches a paginated list of an org's members.

Arguments

Name
orgId *
Type
string
Description
The ID of the org.
Name
page_number
Type
number
Description
The page number to return. Starts at 0.
Name
page_size
Type
number
Description
The amount of results per page.
Name
email_search
Type
string
Description
Filter by member email.

Success Response

Name
users
Type
OrgMember[]
Description
An array of API Keys belonging to the provided org.
- user_id string
- email string
- role string
- additional_roles string[]
- possible_roles string[]
- can_be_deleted boolean
- is_enabled boolean
- is_2fa_enabled boolean
Name
total_count
Type
number
Description
The total amount of org members.
Name
page_number
Type
number
Description
The current page.
Name
page_size
Type
number
Description
The maximum amount of results of the page.
Name
has_more_results
Type
boolean
Description
Returns true of there are more results beyond the current page.

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.

Name
success
Description
Successful request.
Name
orgNotFound
Description
The provided Org ID was not found.
Name
orgsNotEnabled
Description
Organizations are not enabled for the project.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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);
    },
});

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
}

fetchOrgSettings

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

Arguments

Name
org_id *
Type
string
Description
The ID of the org.

Success Response

Name
org_name
Type
string
Description
The name of the organization.
Name
user_can_edit_org_access
Type
boolean
Description
Returns true if the user has the necessary permissions to update the org settings.
Name
user_can_update_metadata
Type
boolean
Description
Returns true if the user has the necessary permissions to update the org metadata.
Name
autojoin_by_domain
Type
boolean
Description
If a domain is set for the org, new users can join the org if their domain matches the org's domain.
Name
restrict_to_domain
Type
boolean
Description
If a domain is set for the org, only allow users with that domain to join.
Name
require_2fa_by
Type
string | null
Description
The date by which 2FA is required for the org. If null, 2FA is not required.
Name
existing_domain
Type
string | null
Description
The org's current domain, if one is set.
Name
current_user_domain
Type
string
Description
The domain of the current user.
Name
current_user_domain_is_personal
Type
boolean
Description
Returns true if the current user's domain is personal (e.g. gmail.com).
Name
can_setup_saml
Type
boolean
Description
Returns true if the org can set up SAML.
Name
is_saml_enabled
Type
boolean
Description
Returns true if the org has SAML enabled.
Name
is_saml_in_test_mode
Type
boolean
Description
Returns true if the org has SAML in test mode.
Name
can_setup_scim
Type
boolean
Description
Returns true if the org can set up SCIM.
Name
is_scim_enabled
Type
boolean
Description
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.

Name
success
Description
Successful request.
Name
orgsNotEnabled
Description
Orgs are not enabled in the PropelAuth dashboard.
Name
orgNotFound
Description
The provided organization was not found.
Name
forbidden
Description
The user does not have permission to view the organization settings.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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.')
    },
})

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
}

fetchPendingOrgInvites

Fetches a paginated list of an org's invites.

Arguments

Name
orgId *
Type
string
Description
The ID of the org.
Name
page_number
Type
number
Description
The page number to return. Starts at 0.
Name
page_size
Type
number
Description
The amount of results per page.
Name
email_search
Type
string
Description
Filter by member email.

Success Response

Name
pending_invites
Type
PendingOrgInvite[]
Description
An array of invites for the provided org.
- email string
- role string
- additional_roles string[]
- expires_at_seconds number
Name
total_count
Type
number
Description
The total amount of org members.
Name
page_number
Type
number
Description
The current page.
Name
page_size
Type
number
Description
The maximum amount of results of the page.
Name
has_more_results
Type
boolean
Description
Returns true of there are more results beyond the current page.

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.

Name
success
Description
Successful request.
Name
orgNotFound
Description
The provided Org ID was not found.
Name
orgsNotEnabled
Description
Organizations are not enabled for the project.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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);
    },
});

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
}

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

Name
page_number
Type
number
Description
The page number to return. Starts at 0.
Name
page_size
Type
number
Description
The amount of results per page.
Name
api_key_search
Type
string
Description
Filter by Key ID.

Success Response

Name
api_keys
Type
PersonalApiKey[]
Description
An array of API Keys belonging to the logged in user.
- api_key_id string
- created_at number
- expires_at_seconds number | null
- metadata object | null
Name
total_api_keys
Type
number
Description
The total amount of API keys belonging to the user.
Name
current_page
Type
number
Description
The current page.
Name
page_size
Type
number
Description
The maximum amount of results of the page.
Name
has_more_results
Type
boolean
Description
Returns true of there are more results beyond the current page.

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.

Name
success
Description
Successful request.
Name
personalApiKeysDisabled
Description
API keys are not enabled in your PropelAuth project.
Name
badRequest
Description
Incorrect arguments provided.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{
    "api_keys": [
        {
            "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
}

inviteUserToOrg

Sends an invitation to a user to join an organization.

Arguments

Name
org_id *
Type
string
Description
The ID of the org.
Name
email *
Type
string
Description
The email of the user who is being invited.
Name
role *
Type
string
Description
The role the user will have.
Name
additional_roles
Type
string[]
Description
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.

Name
success
Description
Successful request.
Name
noInvitePermission
Description
The user does not have permission to invite other users to the organization.
Name
orgNotFound
Description
The org ID cannot be found.
Name
orgsNotEnabled
Description
Organizations are not enabled for the project.
Name
userAlreadyInOrg
Description
The email provided is already a member of the organization.
Name
orgMaxUsersLimitExceeded
Description
The org's user limit has already been met.
Name
badRequest
Description
Incorrect arguments given.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{}

joinOrg

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

Arguments

Name
org_id *
Type
string
Description
The ID of the org to join.

Success Response

Name
org_id
Type
string
Description
The ID of the org.
Name
first_org
Type
boolean
Description
If the org is the first org the user belongs to.

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.

Name
success
Description
Successful request.
Name
userAlreadyInTooManyOrgs
Description
User already belongs to the maximum amount of orgs.
Name
orgMaxUsersLimitExceeded
Description
The org's user limit has already been met.
Name
orgsNotEnabled
Description
Organizations are not enabled for the project.
Name
orgNotFound
Description
The org ID cannot be found.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

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

Accepts either a domain, email, or org_id and returns a SAML login URL for the specified organization.

Arguments

Name
email
Type
string
Description
The email of the user.
Name
domain
Type
string
Description
The domain of the user or organization, such as `acme.com`.
Name
org_id
Type
string
Description
The ID of the organization.

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.

Name
success
Description
Successful request.
Name
orgNotFound
Description
The provided org_id or domain is not tied to an existing org with SAML enabled.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

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

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

Name
provider *
Type
SocialLoginProvider
Description
The provider to login with. Must be one of these options:
- Google
- Github
- Microsoft
- Slack
- Salesforce
- Linkedin
- Outreach
- Quickbooks
- Xero
- Salesloft
- Atlassian
- Apple

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>

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

Arguments

Name
email *
Type
string
Description
The email of the user to send a magic link to.
Name
create_if_doesnt_exist *
Type
boolean
Description
If set to true, a new user will be created if the email is not associated with an existing 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.

Name
success
Description
Successful request.
Name
passwordlessLoginDisabled
Description
Passwordless login is disabled in the PropelAuth Dashboard.
Name
userAccountDisabled
Description
User cannot login due to their account being disabled.
Name
userAccountLocked
Description
User cannot login due to their account being locked.
Name
cannotSignupWithPersonalEmail
Description
Personal email domains are disabled in the PropelAuth Dashboard.
Name
domainNotAllowed
Description
The email domain is blocked in the PropelAuth Dashboard.
Name
badRequest
Description
Incorrect arguments provided.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{}

removeUserFromOrg

Removes the provided user from the provided organization.

Arguments

Name
org_id *
Type
string
Description
The ID of the org.
Name
user_id *
Type
string
Description
The ID of the user to remove from the 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.

Name
success
Description
Successful request.
Name
orgNotFound
Description
The org ID cannot be found.
Name
userNotFoundInOrg
Description
User ID not found.
Name
noRemovePermission
Description
The user doing the action does not have permission to remove the provided user from the org.
Name
orgsNotEnabled
Description
Organizations not enabled for this project.
Name
mustBeAtLeastOneOwner
Description
The user you're trying to remove is the only Owner of the org.
Name
badRequest
Description
Incorrect arguments given.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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);
    },
})

Successful Response

{}

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.

Name
success
Description
Successful request.
Name
rateLimited
Description
Too many confirmation emails have been sent to this user in a short period of time.
Name
emailAlreadyConfirmed
Description
The user has already confirmed their email address.
Name
badRequest
Description
Incorrect arguments provided.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
    badRequest(error) {
        console.error('Bad request', error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})

Successful Response

{}

revokeUserOrgInvitation

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

Arguments

Name
org_id *
Type
string
Description
The ID of the org.
Name
email *
Type
string
Description
The email of 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.

Name
success
Description
Successful request.
Name
orgNotFound
Description
The org ID cannot be found.
Name
noRevokeInvitePermission
Description
The user doing the action does not have permission to revoke an invitation for the org.
Name
orgsNotEnabled
Description
Organizations not enabled for this project.
Name
badRequest
Description
Incorrect arguments given.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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);
    },
});

Successful Response

{}

sendForgotPasswordEmail

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

Arguments

Name
email *
Type
string
Description
The email of the user

Success Response

Name
message
Type
string
Description
A confirmation message, such as 'If that email address is in our database, we will send you an email to reset your password.'
Name
sniper_links
Type
dictionary
Description
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.

Name
success
Description
Successful request.
Name
badRequest
Description
Incorrect arguments provided.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

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"
    }
}

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

Arguments

Name
email *
Type
string
Description
The email of the user to create.
Name
password *
Type
string
Description
The password of the user to create.
Name
username
Type
string
Description
The username of the user to create. See User Properties for more information.
Name
first_name
Type
string
Description
The first name of the user to create. See User Properties for more information.
Name
last_name
Type
string
Description
The last name of the user to create. See User Properties for more information.
Name
properties
Type
dictionary
Description
A dictionary of custom properties of the user to create. See Custom User Properties for more information.
Name
invite_token
Type
string
Description
The token included as a invite_token URL parameter in the invite link sent to the invited user.

Success Response

Name
login_state
Type
LoginState
Description
Returns one of the following:
- LOGIN_REQUIRED
- TWO_FACTOR_REQUIRED
- EMAIL_NOT_CONFIRMED_YET
- USER_MISSING_REQUIRED_PROPERTIES
- USER_MUST_BE_IN_AT_LEAST_ONE_ORG
- UPDATE_PASSWORD_REQUIRED
- TWO_FACTOR_ENROLLMENT_REQUIRED
- LOGGED_IN
Name
user_id
Type
string
Description
The ID of the user that was created.

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.

Name
success
Description
Successful request.
Name
signupDisabled
Description
Signups are disabled in the PropelAuth Dashboard.
Name
badRequest
Description
Incorrect arguments provided.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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..."
})
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)
    },
})

Successful Response

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

updateEmail

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

Arguments

Name
new_email *
Type
string
Description
The email address the user wants to change their email to.
Name
password
Type
string
Description
An optional argument to check if the user can provide the correct password. Required if the user has a password set.

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.

Name
success
Description
Successful request.
Name
cannotChangeEmailDueToOrgMembership
Description
User belongs to an organization that enforces an email domain restriction.
Name
rateLimit
Description
Too many requests made for this specific user to update their email.
Name
emailChangeDisabled
Description
'Allow users to change their email' disabled in PropelAuth dashboard.
Name
failedToSendEmail
Description
There was an error in sending the user the confirmation email.
Name
incorrectPassword
Description
The user provided an incorrect password.
Name
userAccountLocked
Description
The user's account is locked.
Name
badRequest
Description
Incorrect arguments given.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{}

updateOrgSettings

Updates the settings for an organization.

Arguments

Name
org_id *
Type
string
Description
The ID of the org to be updated.
Name
name
Type
string
Description
The new name of the org.
Name
allow_users_to_join_by_domain
Type
boolean
Description
If a domain is set for the org, new users can join the org if their domain matches the org's domain.
Name
restrict_invites_by_domain
Type
boolean
Description
If a domain is set for the org, only allow users with that domain to join.
Name
require_2fa_by
Type
date
Description
If requiring 2FA for an org, the date you want to enforce it by.

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.

Name
success
Description
Successful request.
Name
orgsNotEnabled
Description
Organizations are not enabled in this project.
Name
orgNotFound
Description
The provided orgId was not found
Name
forbidden
Description
The user does not have permission to edit the org.
Name
badRequest
Description
Incorrect arguments given.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{}

updatePassword

Updates the logged in user's password.

Arguments

Name
password *
Type
string
Description
The user's new password.
Name
current_password
Type
string
Description
An optional argument to check if the user can provide the correct current password. Required if the user already has a password set.

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.

Name
success
Description
Successful request.
Name
incorrectPassword
Description
User was not able to provide the correct current password.
Name
userAccountLocked
Description
The user's account is locked.
Name
badRequest
Description
Incorrect arguments given.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{}

updateUserMetadata

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

Arguments

Name
username
Type
string
Description
The user's new username.
Name
first_name
Type
string
Description
The user's new first name.
Name
last_name
Type
string
Description
The user's new last name.
Name
properties
Type
{[key: string]: unknown}
Description
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.

Name
success
Description
Successful request.
Name
badRequest
Description
Incorrect arguments given.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{}

updateUserRoleInOrg

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

Arguments

Name
org_id *
Type
string
Description
The ID of the org.
Name
user_id *
Type
string
Description
The ID of the user.
Name
role *
Type
string
Description
The role the user will be updated to.
Name
additional_roles
Type
string[]
Description
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.

Name
success
Description
Successful request.
Name
noUpdateRolePermission
Description
User does not have permission to update this user's role.
Name
userNotFoundInOrg
Description
User ID not found.
Name
orgsNotEnabled
Description
Organizations not enabled for this project.
Name
badRequest
Description
Incorrect arguments given.
Name
unauthorized
Description
The user is not logged in.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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);
    },
});

Successful Response

{}

Verifies the user's MFA code for login.

Arguments

Name
code *
Type
string
Description
The user's MFA backup code

Success Response

Name
login_state
Type
LoginState
Description
Returns one of the following:
- LOGIN_REQUIRED
- TWO_FACTOR_REQUIRED
- EMAIL_NOT_CONFIRMED_YET
- USER_MISSING_REQUIRED_PROPERTIES
- USER_MUST_BE_IN_AT_LEAST_ONE_ORG
- UPDATE_PASSWORD_REQUIRED
- TWO_FACTOR_ENROLLMENT_REQUIRED
- LOGGED_IN

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.

Name
success
Description
Successful request.
Name
invalidCode
Description
Invalid code provided.
Name
mfaCookieTimeout
Description
The user's MFA session has timed out. They must log in again to continue.
Name
userAccountDisabled
Description
User cannot login due to their account being disabled.
Name
userAccountLocked
Description
User cannot login due to their account being locked.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{
    "login_state": "Finished"
}

Verifies the user's MFA code for login.

Arguments

Name
code *
Type
string
Description
The MFA code generated by your user's authenticator.

Success Response

Name
login_state
Type
LoginState
Description
Returns one of the following:
- LOGIN_REQUIRED
- TWO_FACTOR_REQUIRED
- EMAIL_NOT_CONFIRMED_YET
- USER_MISSING_REQUIRED_PROPERTIES
- USER_MUST_BE_IN_AT_LEAST_ONE_ORG
- UPDATE_PASSWORD_REQUIRED
- TWO_FACTOR_ENROLLMENT_REQUIRED
- LOGGED_IN

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.

Name
success
Description
Successful request.
Name
mfaCookieTimeout
Description
The user's MFA session has timed out. They must log in again to continue.
Name
userAccountDisabled
Description
User cannot login due to their account being disabled.
Name
userAccountLocked
Description
User cannot login due to their account being locked.
Name
badRequest
Description
Incorrect arguments provided or incorrect code provided.
Name
unexpectedOrUnhandled
Description
An unexpected error occurred.

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)
    },
})

Successful Response

{
    "login_state": "Finished"
}