Login API Reference Documentation

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

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

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

{}

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

{}

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

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