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](https://docs.propelauth.com/)
Close banner
# Full Reference Documentation
## [createOrg](https://ui.propelauth.com/reference-docs\#create-org)
Creates a new org and automatically adds the logged in user to it.
## Arguments
- Name`name` \*TypestringDescriptionThe name of the org to be created
- Name`allow_users_to_join_by_domain` \*TypebooleanDescriptionIf 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` \*TypebooleanDescriptionIf a domain is set for the org, only allow users with that domain to join.
## Success Response
- Name`org_id`TypestringDescriptionThe ID of the new org.
- Name`first_org`TypebooleanDescriptionIf 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`DescriptionSuccessful request.
- Name`cannotCreateOrgs`DescriptionThe user does not have permission to create orgs.
- Name`cannotUsePersonalDomain`DescriptionThe user provided a domain such as "gmail.com", "microsoft.com", etc.
- Name`userAlreadyInTooManyOrgs`DescriptionUser already belongs to the maximum amount of orgs.
- Name`badRequest`DescriptionIncorrect arguments provided.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{
"org_id": "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
"first_org": true
}
```
CopyCopied!
* * *
## [createOrgApiKey](https://ui.propelauth.com/reference-docs\#create-org-api-key)
Creates an Org API key for the provided organization.
## Arguments
- Name`orgId` \*TypestringDescriptionThe ID of the org to create an API key for
- Name`expirationOption` \*TypestringDescriptionCan be one of the following: 'TwoWeeks' \| 'OneMonth' \| 'ThreeMonths' \| 'SixMonths' \| 'OneYear' \| 'Never'
- Name`displayName`TypestringDescriptionThe display name of the API key
## Success Response
- Name`api_key_id`TypestringDescriptionThe ID of the API Key.
- Name`api_key_token`TypestringDescriptionThe 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`DescriptionSuccessful request.
- Name`invalidExpirationOption`DescriptionIncorrect argument provided for 'expirationOption'
- Name`noOrgApiKeyPermission`DescriptionUser does not have permission to create an org API key.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`badRequest`DescriptionIncorrect arguments provided.
- Name`unexpectedOrUnhandled`DescriptionAn unexpected error occurred.
### 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](https://ui.propelauth.com/reference-docs\#create-personal-api-key)
Creates a Personal API key for the logged in user.
## Arguments
- Name`expirationOption` \*TypestringDescriptionCan be one of the following: 'TwoWeeks' \| 'OneMonth' \| 'ThreeMonths' \| 'SixMonths' \| 'OneYear' \| 'Never'
- Name`displayName`TypestringDescriptionThe display name of the API key
## Success Response
- Name`api_key_id`TypestringDescriptionThe ID of the API Key.
- Name`api_key_token`TypestringDescriptionThe 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`DescriptionSuccessful request.
- Name`invalidExpirationOption`DescriptionIncorrect argument provided for 'expirationOption'
- Name`noPersonalApiKeyPermission`DescriptionUser does not have permission to create a personal API key.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`badRequest`DescriptionIncorrect arguments provided.
- Name`unexpectedOrUnhandled`DescriptionAn unexpected error occurred.
### 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](https://ui.propelauth.com/reference-docs\#delete-account)
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`DescriptionSuccessful request.
- Name`actionDisabled`DescriptionThe 'Users can delete their own accounts' setting in your PropelAuth dashboard is disabled
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [deleteApiKey](https://ui.propelauth.com/reference-docs\#delete-api-key)
Deletes the provided API Key.
## Arguments
- Name`apiKeyId` \*TypestringDescriptionThe 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`DescriptionSuccessful request.
- Name`apiKeyNotFound`DescriptionAPI Key ID not associated with an API key that belongs to the user.
- Name`noApiKeyPermission`DescriptionUser does not have permission to delete the API key.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [deleteOrg](https://ui.propelauth.com/reference-docs\#delete-org)
Deletes the provided organization.
## Arguments
- Name`orgId` \*TypestringDescriptionThe 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`DescriptionSuccessful request.
- Name`orgNotFound`DescriptionThe provided org does not exist.
- Name`actionDisabled`DescriptionThe 'Users can delete their own orgs' setting is disabled in your PropelAuth dashboard.
- Name`noDeletePermission`DescriptionUser does not have permission to delete the org.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [disableMfa](https://ui.propelauth.com/reference-docs\#disable-mfa)
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`DescriptionSuccessful request.
- Name`alreadyDisabled`DescriptionMFA not enabled for user.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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')
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [emailPasswordLogin](https://ui.propelauth.com/reference-docs\#email-password-login)
Accepts a user's email and password to log them in.
## Arguments
- Name`email` \*TypestringDescriptionThe email of the user to log in.
- Name`password` \*TypestringDescriptionThe password of the user to log in.
## Success Response
- Name`login_state`TypeLoginStateDescription
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`DescriptionSuccessful request.
- Name`passwordLoginDisabled`DescriptionPassword login is disabled in the PropelAuth Dashboard.
- Name`userAccountDisabled`DescriptionUser cannot login due to their account being disabled.
- Name`userAccountLocked`DescriptionUser cannot login due to their account being locked.
- Name`invalidCredentials`DescriptionThe email or password provided is incorrect.
- Name`badRequest`DescriptionIncorrect arguments provided.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{
"login_state": "Finished"
}
```
CopyCopied!
* * *
## [enableMfa](https://ui.propelauth.com/reference-docs\#enable-mfa)
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](https://ui.propelauth.com/reference-docs#fetch-mfa-status-with-new-secret).
## Arguments
- Name`code` \*TypestringDescriptionThe 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`DescriptionSuccessful request.
- Name`alreadyEnabled`DescriptionUser has MFA enabled already.
- Name`badRequest`DescriptionIncorrect arguments provided. This is the error you will get if the code is incorrect.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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')
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [fetchExpiredInvites](https://ui.propelauth.com/reference-docs\#fetch-expired-invites)
Fetches a paginated list of an org's expired invites.
## Arguments
- Name`orgId` \*TypestringDescriptionThe ID of the org to fetch expired invites for.
- Name`page_number`TypenumberDescriptionThe page number to return. Starts at 0.
- Name`page_size`TypenumberDescriptionThe amount of results per page.
- Name`email_search`TypestringDescriptionFilter by invite email.
## Success Response
- Name`expired_invites`TypeExpiredOrgInvite\[\]Description
An array of expired invites for the provided org.
- `email` _string_
- `role` _string_
- `additional_roles` _string\[\]_
- `expires_at_seconds` _number_
- Name`total_count`TypenumberDescriptionThe total amount of expired org invites.
- Name`page_number`TypenumberDescriptionThe current page.
- Name`page_size`TypenumberDescriptionThe maximum amount of results of the page.
- Name`has_more_results`TypebooleanDescriptionReturns 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`DescriptionSuccessful request.
- Name`orgNotFound`DescriptionThe provided Org ID was not found.
- Name`orgsNotEnabled`DescriptionOrganizations are not enabled for the project.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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);
},
});
```
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](https://ui.propelauth.com/reference-docs\#fetch-joinable-orgs)
Returns an array of organizations that the user can join based on their email domain.
## Success Response
- Name`orgs`TypeJoinableOrg\[\]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`DescriptionSuccessful request.
- Name`orgsNotEnabled`DescriptionOrganizations are not enabled in the PropelAuth Dashboard.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{
"orgs": [\
{\
"id": "org_123",\
"name": "Acme Corp"\
},\
{\
"id": "org_456",\
"name": "Widget Co"\
}\
]
}
```
CopyCopied!
* * *
## [fetchLoginState](https://ui.propelauth.com/reference-docs\#fetch-login-state)
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`TypeLoginStateDescription
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.
- Name`success`DescriptionSuccessful request.
- Name`unexpectedOrUnhandled`DescriptionAn 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.')
},
})
```
CopyCopied!
### Successful Response
```
{
"login_state": "LoginRequired"
}
```
CopyCopied!
* * *
## [fetchMfaStatusWithNewSecret](https://ui.propelauth.com/reference-docs\#fetch-mfa-status-with-new-secret)
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`TypestringDescription
The type of response depending on if the user has MFA enabled or disabled. Returns either `Disabled` or `Enabled`.
- Name`mfa_enabled`TypebooleanDescription
Returns `true` if the current user has MFA enabled. Otherwise, returns `false`.
- Name`backup_codes`Typestring\[\]Description
Only returned if `mfa_enabled` equals `true`. Returns the current users MFA backup codes.
- Name`new_secret`TypestringDescription
Only returned if `mfa_enabled` equals `false`.
- Name`new_qr`TypestringDescription
Only returned if `mfa_enabled` equals `false`. The QR code the current user can scan to enable MFA.
- Name`has_password`TypebooleanDescriptionIf 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`DescriptionSuccessful request.
- Name`emailNotConfirmed`DescriptionUser has not yet confirmed their email address.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
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](https://ui.propelauth.com/reference-docs\#fetch-org-api-keys)
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` \*TypestringDescriptionThe ID of the org to fetch expired invites for.
- Name`page_number`TypenumberDescriptionThe page number to return. Starts at 0.
- Name`page_size`TypenumberDescriptionThe amount of results per page.
- Name`api_key_search`TypestringDescriptionFilter by Key ID.
- Name`sort_by`TypestringDescriptionCan be one of the following: 'CreatedAtAsc' \| 'CreatedAtDesc' \| 'ExpiresAtAsc' \| 'ExpiresAtDesc'
## Success Response
- Name`api_keys`TypeOrgApiKey\[\]Description
An array of API Keys belonging to the provided org.
- `display_name` _string \| null_
- `api_key_id` _string_
- `created_at` _number_
- `expires_at_seconds` _number \| null_
- `metadata` _object \| null_
- Name`total_api_keys`TypenumberDescriptionThe total amount of API keys belonging to the org.
- Name`current_page`TypenumberDescriptionThe current page.
- Name`page_size`TypenumberDescriptionThe maximum amount of results of the page.
- Name`has_more_results`TypebooleanDescriptionReturns 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`DescriptionSuccessful request.
- Name`orgApiKeysDisabled`DescriptionOrg API keys are not enabled in your PropelAuth project.
- Name`badRequest`DescriptionIncorrect arguments provided.
- Name`orgNotFound`DescriptionThe provided Org ID was not found.
- Name`cannotAccessOrgApiKeys`DescriptionThe user does not have permission to access org API keys.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
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](https://ui.propelauth.com/reference-docs\#fetch-org-members)
Fetches a paginated list of an org's members.
## Arguments
- Name`orgId` \*TypestringDescriptionThe ID of the org.
- Name`page_number`TypenumberDescriptionThe page number to return. Starts at 0.
- Name`page_size`TypenumberDescriptionThe amount of results per page.
- Name`email_search`TypestringDescriptionFilter by member email.
## Success Response
- Name`users`TypeOrgMember\[\]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`TypenumberDescriptionThe total amount of org members.
- Name`page_number`TypenumberDescriptionThe current page.
- Name`page_size`TypenumberDescriptionThe maximum amount of results of the page.
- Name`has_more_results`TypebooleanDescriptionReturns 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.
### 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](https://ui.propelauth.com/reference-docs\#fetch-org-settings)
Fetches the provided org's settings and information, such as org name, SAML status, 2FA requirements, and more.
## Arguments
- Name`org_id` \*TypestringDescriptionThe ID of the org.
## Success Response
- Name`org_name`TypestringDescriptionThe name of the organization.
- Name`user_can_edit_org_access`TypebooleanDescriptionReturns true if the user has the necessary permissions to update the org settings.
- Name`user_can_update_metadata`TypebooleanDescriptionReturns true if the user has the necessary permissions to update the org metadata.
- Name`autojoin_by_domain`TypebooleanDescriptionIf 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`TypebooleanDescriptionIf a domain is set for the org, only allow users with that domain to join.
- Name`require_2fa_by`Typestring \| nullDescriptionThe date by which 2FA is required for the org. If null, 2FA is not required.
- Name`existing_domain`Typestring \| nullDescriptionThe org's current domain, if one is set.
- Name`current_user_domain`TypestringDescriptionThe domain of the current user.
- Name`current_user_domain_is_personal`TypebooleanDescriptionReturns true if the current user's domain is personal (e.g. gmail.com).
- Name`can_setup_saml`TypebooleanDescription
Returns true if the org can set up [SAML](https://docs.propelauth.com/overview/authentication/saml).
- Name`is_saml_enabled`TypebooleanDescription
Returns true if the org has [SAML](https://docs.propelauth.com/overview/authentication/saml) enabled.
- Name`is_saml_in_test_mode`TypebooleanDescription
Returns true if the org has [SAML](https://docs.propelauth.com/overview/authentication/saml) in test mode.
- Name`can_setup_scim`TypebooleanDescription
Returns true if the org can set up [SCIM](https://docs.propelauth.com/overview/authentication/scim).
- Name`is_scim_enabled`TypebooleanDescription
Returns true if the org can set has [SCIM](https://docs.propelauth.com/overview/authentication/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`DescriptionSuccessful request.
- Name`orgsNotEnabled`DescriptionOrgs are not enabled in the PropelAuth dashboard.
- Name`orgNotFound`DescriptionThe provided organization was not found.
- Name`forbidden`DescriptionThe user does not have permission to view the organization settings.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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.')
},
})
```
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](https://ui.propelauth.com/reference-docs\#fetch-pending-org-invites)
Fetches a paginated list of an org's invites.
## Arguments
## Success Response
- Name`pending_invites`TypePendingOrgInvite\[\]Description
An array of invites for the provided org.
- `email` _string_
- `role` _string_
- `additional_roles` _string\[\]_
- `expires_at_seconds` _number_
## 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](https://ui.propelauth.com/reference-docs\#fetch-personal-api-keys)
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`TypenumberDescriptionThe page number to return. Starts at 0.
- Name`page_size`TypenumberDescriptionThe amount of results per page.
- Name`api_key_search`TypestringDescriptionFilter by Key ID.
- Name`sort_by`TypestringDescriptionCan be one of the following: 'CreatedAtAsc' \| 'CreatedAtDesc' \| 'ExpiresAtAsc' \| 'ExpiresAtDesc'
## Success Response
- Name`api_keys`TypePersonalApiKey\[\]Description
An array of API Keys belonging to the logged in user.
- `display_name` _string \| null_
- `api_key_id` _string_
- `created_at` _number_
- `expires_at_seconds` _number \| null_
- `metadata` _object \| null_
- Name`total_api_keys`TypenumberDescriptionThe total amount of API keys belonging to the user.
- Name`current_page`TypenumberDescriptionThe current page.
- Name`page_size`TypenumberDescriptionThe maximum amount of results of the page.
- Name`has_more_results`TypebooleanDescriptionReturns 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`DescriptionSuccessful request.
- Name`personalApiKeysDisabled`DescriptionAPI keys are not enabled in your PropelAuth project.
- Name`badRequest`DescriptionIncorrect arguments provided.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
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](https://ui.propelauth.com/reference-docs\#invite-user-to-org)
Sends an invitation to a user to join an organization.
## Arguments
- Name`org_id` \*TypestringDescriptionThe ID of the org.
- Name`email` \*TypestringDescriptionThe email of the user who is being invited.
- Name`role` \*TypestringDescriptionThe role the user will have.
- Name`additional_roles`Typestring\[\]Description
If using [multiple roles per user](https://docs.propelauth.com/overview/authorization/managing-roles-permissions#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`DescriptionSuccessful request.
- Name`noInvitePermission`DescriptionThe user does not have permission to invite other users to the organization.
- Name`orgNotFound`DescriptionThe org ID cannot be found.
- Name`orgsNotEnabled`DescriptionOrganizations are not enabled for the project.
- Name`userAlreadyInOrg`DescriptionThe email provided is already a member of the organization.
- Name`orgMaxUsersLimitExceeded`DescriptionThe org's user limit has already been met.
- Name`badRequest`DescriptionIncorrect arguments given.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [joinOrg](https://ui.propelauth.com/reference-docs\#join-org)
Adds the logged in user as a member of the provided organization.
## Arguments
- Name`org_id` \*TypestringDescriptionThe ID of the org to join.
## Success Response
- Name`org_id`TypestringDescriptionThe ID of the org.
- Name`first_org`TypebooleanDescriptionIf 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`DescriptionSuccessful request.
- Name`userAlreadyInTooManyOrgs`DescriptionUser already belongs to the maximum amount of orgs.
- Name`orgMaxUsersLimitExceeded`DescriptionThe org's user limit has already been met.
- Name`orgsNotEnabled`DescriptionOrganizations are not enabled for the project.
- Name`orgNotFound`DescriptionThe org ID cannot be found.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{
"org_id": "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
"first_org": true
}
```
CopyCopied!
* * *
## [loginViaSamlForOrg](https://ui.propelauth.com/reference-docs\#login-via-saml-for-org)
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
- Name`email`TypestringDescriptionThe email of the user.
- Name`domain`TypestringDescriptionThe domain of the user or organization, such as \`acme.com\`.
- Name`org_id`TypestringDescriptionThe 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`DescriptionSuccessful request.
- Name`orgNotFound`DescriptionThe provided org\_id or domain is not tied to an existing org with SAML enabled.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{
"login_url": "https://example.com/saml/login"
}
```
CopyCopied!
* * *
## [loginWithSocialProvider](https://ui.propelauth.com/reference-docs\#login-with-social-provider)
Redirects the user to login with the specified [Social Login provider](https://docs.propelauth.com/sso/social-login). If signups are enabled, will create a new user if one does not already exist.
## Arguments
- Name`provider` \*TypeSocialLoginProviderDescription
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
// Javascript version
```
CopyCopied!
* * *
## [passwordlessLogin](https://ui.propelauth.com/reference-docs\#passwordless-login)
Sends a magic link to the user's email address to log them in.
## Arguments
- Name`email` \*TypestringDescriptionThe email of the user to send a magic link to.
- Name`create_if_doesnt_exist` \*TypebooleanDescriptionIf 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`DescriptionSuccessful request.
- Name`passwordlessLoginDisabled`DescriptionPasswordless login is disabled in the PropelAuth Dashboard.
- Name`userAccountDisabled`DescriptionUser cannot login due to their account being disabled.
- Name`userAccountLocked`DescriptionUser cannot login due to their account being locked.
- Name`cannotSignupWithPersonalEmail`DescriptionPersonal email domains are disabled in the PropelAuth Dashboard.
- Name`domainNotAllowed`DescriptionThe email domain is blocked in the PropelAuth Dashboard.
- Name`badRequest`DescriptionIncorrect arguments provided.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [removeUserFromOrg](https://ui.propelauth.com/reference-docs\#remove-user-from-org)
Removes the provided user from the provided organization.
## Arguments
- Name`org_id` \*TypestringDescriptionThe ID of the org.
- Name`user_id` \*TypestringDescriptionThe 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`DescriptionSuccessful request.
- Name`orgNotFound`DescriptionThe org ID cannot be found.
- Name`userNotFoundInOrg`DescriptionUser ID not found.
- Name`noRemovePermission`DescriptionThe user doing the action does not have permission to remove the provided user from the org.
- Name`orgsNotEnabled`DescriptionOrganizations not enabled for this project.
- Name`mustBeAtLeastOneOwner`DescriptionThe user you're trying to remove is the only Owner of the org.
- Name`badRequest`DescriptionIncorrect arguments given.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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);
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [resendEmailConfirmation](https://ui.propelauth.com/reference-docs\#resend-email-confirmation)
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`DescriptionSuccessful request.
- Name`rateLimited`DescriptionToo many confirmation emails have been sent to this user in a short period of time.
- Name`emailAlreadyConfirmed`DescriptionThe user has already confirmed their email address.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
unexpectedOrUnhandled(error) {
console.error('Unexpected or unhandled', error.user_facing_error)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [revokeUserOrgInvitation](https://ui.propelauth.com/reference-docs\#revoke-user-org-invitation)
Revokes an existing invitation to a user to join an organization.
## Arguments
- Name`org_id` \*TypestringDescriptionThe ID of the org.
- Name`email` \*TypestringDescriptionThe 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`DescriptionSuccessful request.
- Name`orgNotFound`DescriptionThe org ID cannot be found.
- Name`noRevokeInvitePermission`DescriptionThe user doing the action does not have permission to revoke an invitation for the org.
- Name`orgsNotEnabled`DescriptionOrganizations not enabled for this project.
- Name`badRequest`DescriptionIncorrect arguments given.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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);
},
});
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [sendForgotPasswordEmail](https://ui.propelauth.com/reference-docs\#send-forgot-password-email)
Sends the user an email to reset their password if an account with that email exists.
## Arguments
- Name`email` \*TypestringDescriptionThe email of the user
## Success Response
- Name`message`TypestringDescriptionA 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`TypedictionaryDescription
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`DescriptionSuccessful request.
- Name`badRequest`DescriptionIncorrect arguments provided.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
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](https://ui.propelauth.com/reference-docs\#signup)
Create a user for your application using email and password. See [passwordlesslogin](https://ui.propelauth.com/reference-docs#passwordless-login) and [loginWithSocialProvider](https://ui.propelauth.com/reference-docs#login-with-social-provider) for alternative ways to sign users up.
## Arguments
- Name`email` \*TypestringDescriptionThe email of the user to create.
- Name`password` \*TypestringDescriptionThe password of the user to create.
- Name`username`TypestringDescription
The username of the user to create. See [User Properties](https://docs.propelauth.com/overview/user-management/user-properties) for more information.
- Name`first_name`TypestringDescription
The first name of the user to create. See [User Properties](https://docs.propelauth.com/overview/user-management/user-properties) for more information.
- Name`last_name`TypestringDescription
The last name of the user to create. See [User Properties](https://docs.propelauth.com/overview/user-management/user-properties) for more information.
- Name`properties`TypedictionaryDescription
A dictionary of custom properties of the user to create. See [Custom User Properties](https://docs.propelauth.com/overview/user-management/user-properties#custom-user-properties) for more information.
- Name`invite_token`TypestringDescription
The token included as a `invite_token` URL parameter in the invite link sent to the invited user.
- Name`turnstile_token`TypestringDescription
The token returned by the [Turnstile widget](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/). Required if using the PropelAuth [Cloudflare Turnstile Integration](https://docs.propelauth.com/integrations/turnstile).
## Success Response
- Name`login_state`TypeLoginStateDescription
Returns one of the following:
- Name`user_id`TypestringDescriptionThe 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`DescriptionSuccessful request.
- Name`signupDisabled`DescriptionSignups are disabled in the PropelAuth Dashboard.
- Name`badRequest`DescriptionIncorrect arguments provided.
- Name`unexpectedOrUnhandled`DescriptionAn 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...",
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](https://ui.propelauth.com/reference-docs\#update-api-key)
Updates the display name of an API Key.
## Arguments
- Name`api_key_id` \*TypestringDescriptionThe ID of the API Key to be updated.
- Name`display_name` \*TypestringDescriptionThe new name of 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`DescriptionSuccessful request.
- Name`apiKeyNotFound`DescriptionAPI Key ID not associated with an API key that belongs to the user.
- Name`noApiKeyPermission`DescriptionUser does not have permission to update the API key.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`badRequest`DescriptionIncorrect arguments given.
- Name`unexpectedOrUnhandled`DescriptionAn unexpected error occurred.
### 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](https://ui.propelauth.com/reference-docs\#update-email)
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` \*TypestringDescriptionThe email address the user wants to change their email to.
- Name`password`TypestringDescriptionAn 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`DescriptionSuccessful request.
- Name`cannotChangeEmailDueToOrgMembership`DescriptionUser belongs to an organization that enforces an email domain restriction.
- Name`rateLimit`DescriptionToo 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`DescriptionThere was an error in sending the user the confirmation email.
- Name`incorrectPassword`DescriptionThe user provided an incorrect password.
- Name`userAccountLocked`DescriptionThe user's account is locked.
- Name`badRequest`DescriptionIncorrect arguments given.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [updateOrgSettings](https://ui.propelauth.com/reference-docs\#update-org-settings)
Updates the settings for an organization.
## Arguments
- Name`org_id` \*TypestringDescriptionThe ID of the org to be updated.
- Name`name`TypestringDescriptionThe new name of the org.
- Name`allow_users_to_join_by_domain`TypebooleanDescriptionIf 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`TypebooleanDescriptionIf a domain is set for the org, only allow users with that domain to join.
- Name`require_2fa_by`TypedateDescriptionIf 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`DescriptionSuccessful request.
- Name`orgsNotEnabled`DescriptionOrganizations are not enabled in this project.
- Name`orgNotFound`DescriptionThe provided orgId was not found
- Name`forbidden`DescriptionThe user does not have permission to edit the org.
- Name`badRequest`DescriptionIncorrect arguments given.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [updatePassword](https://ui.propelauth.com/reference-docs\#update-password)
Updates the logged in user's password.
## Arguments
- Name`password` \*TypestringDescriptionThe user's new password.
- Name`current_password`TypestringDescriptionAn 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`DescriptionSuccessful request.
- Name`incorrectPassword`DescriptionUser was not able to provide the correct current password.
- Name`userAccountLocked`DescriptionThe user's account is locked.
- Name`badRequest`DescriptionIncorrect arguments given.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [updateUserMetadata](https://ui.propelauth.com/reference-docs\#update-user-metadata)
Updates user property fields such as **username**, **first\_name**, **last\_name**, and any [custom user properties](https://docs.propelauth.com/overview/user-management/user-properties#custom-user-properties).
## Arguments
- Name`username`TypestringDescriptionThe user's new username.
- Name`first_name`TypestringDescriptionThe user's new first name.
- Name`last_name`TypestringDescriptionThe user's new last name.
- Name`properties`Type{\[key: string\]: unknown}Description
An object containing any [custom user properties](https://docs.propelauth.com/overview/user-management/user-properties#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`DescriptionSuccessful request.
- Name`badRequest`DescriptionIncorrect arguments given.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [updateUserRoleInOrg](https://ui.propelauth.com/reference-docs\#update-user-role-in-org)
Updates the provided user's role within the provided organization.
## Arguments
- Name`org_id` \*TypestringDescriptionThe ID of the org.
- Name`user_id` \*TypestringDescriptionThe ID of the user.
- Name`role` \*TypestringDescriptionThe role the user will be updated to.
- Name`additional_roles`Typestring\[\]Description
## 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`DescriptionSuccessful request.
- Name`noUpdateRolePermission`DescriptionUser does not have permission to update this user's role.
- Name`userNotFoundInOrg`DescriptionUser ID not found.
- Name`orgsNotEnabled`DescriptionOrganizations not enabled for this project.
- Name`badRequest`DescriptionIncorrect arguments given.
- Name`unauthorized`DescriptionThe user is not logged in.
- Name`unexpectedOrUnhandled`DescriptionAn 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);
},
});
```
CopyCopied!
### Successful Response
```
{}
```
CopyCopied!
* * *
## [verifyMfaBackupCodeForLogin](https://ui.propelauth.com/reference-docs\#verify-mfa-backup-code-for-login)
Verifies the user's MFA code for login.
## Arguments
- Name`code` \*TypestringDescriptionThe user's MFA backup code
## Success Response
- Name`login_state`TypeLoginStateDescription
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.
- Name`success`DescriptionSuccessful request.
- Name`invalidCode`DescriptionInvalid code provided.
- Name`mfaCookieTimeout`DescriptionThe user's MFA session has timed out. They must log in again to continue.
- Name`userAccountDisabled`DescriptionUser cannot login due to their account being disabled.
- Name`userAccountLocked`DescriptionUser cannot login due to their account being locked.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{
"login_state": "Finished"
}
```
CopyCopied!
* * *
## [verifyMfaForLogin](https://ui.propelauth.com/reference-docs\#verify-mfa-for-login)
Verifies the user's MFA code for login.
## Arguments
- Name`code` \*TypestringDescriptionThe MFA code generated by your user's authenticator.
## Success Response
- Name`login_state`TypeLoginStateDescription
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.
- Name`success`DescriptionSuccessful request.
- Name`mfaCookieTimeout`DescriptionThe user's MFA session has timed out. They must log in again to continue.
- Name`userAccountDisabled`DescriptionUser cannot login due to their account being disabled.
- Name`userAccountLocked`DescriptionUser cannot login due to their account being locked.
- Name`badRequest`DescriptionIncorrect arguments provided or incorrect code provided.
- Name`unexpectedOrUnhandled`DescriptionAn 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)
},
})
```
CopyCopied!
### Successful Response
```
{
"login_state": "Finished"
}
```
CopyCopied!
* * *