diff --git a/astro/src/components/api/APIField.astro b/astro/src/components/api/APIField.astro index 0c18a31ea0..e3818a1943 100644 --- a/astro/src/components/api/APIField.astro +++ b/astro/src/components/api/APIField.astro @@ -22,20 +22,23 @@ const { name, description, type, required, optional, immutable, since, defaults, --- {/*If you put the API field inside a conditional block it can break the markdown parsing, `renderif` solves that problem */} {/* Note: if you use a description parameter instead of a body, you'll get a single-line version */} -{ renderif &&
-
- { name } - { type && {type} } - { description && {description} } - { required && required } - { defaults && Defaults to {defaults} } - { show_since && since && } - { immutable && Immutable } - { deprecated && DEPRECATED } - { readonly && } -
-
- -
+{ renderif &&
+
+ + ▶ + { name } + { type && {type} } + { description && {description} } + { required && required } + { defaults && Defaults to {defaults} } + { show_since && since && } + { immutable && Immutable } + { deprecated && DEPRECATED } + { readonly && } + +
+ +
+
} diff --git a/astro/src/content/docs/apis/_user-request-body.mdx b/astro/src/content/docs/apis/_user-request-body.mdx index 3982fd181f..e65789864b 100644 --- a/astro/src/content/docs/apis/_user-request-body.mdx +++ b/astro/src/content/docs/apis/_user-request-body.mdx @@ -25,7 +25,7 @@ You must specify either the **email** or the **username** or both for the User. A tenant has the option to configure one or more email domains to be blocked in order to restrict email domains during user create or update. - Setting this property equal to `true` will override the tenant configuration. See tenant.registrationConfiguration.blockedDomains in the [Tenant API](tenants). + Setting this property equal to `true` will override the tenant configuration. See tenant.registrationConfiguration.blockedDomains in the [Tenant API](/docs/apis/tenants). { props.http_method === 'POST' && diff --git a/astro/src/content/docs/apis/users/bulk-delete.mdx b/astro/src/content/docs/apis/users/bulk-delete.mdx new file mode 100644 index 0000000000..f5334a45d7 --- /dev/null +++ b/astro/src/content/docs/apis/users/bulk-delete.mdx @@ -0,0 +1,103 @@ +--- +title: Bulk Delete Users +description: API documentation for the FusionAuth Bulk Delete Users API. +order: 6 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import Aside from 'src/components/Aside.astro'; +import InlineField from 'src/components/InlineField.astro'; +import JSON from 'src/components/JSON.astro'; +import SearchPreprocessingWarning from "src/content/docs/_shared/_search-preprocessing-warning.mdx"; +import StandardDeleteResponseCodes from 'src/content/docs/apis/_standard-delete-response-codes.astro'; +import UserBulkDeleteRequestBody from 'src/content/docs/apis/_user-bulk-delete-request-body.mdx'; +import UserBulkDeleteResponseBody from 'src/content/docs/apis/_user-bulk-delete-response-body.mdx'; +import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx'; + +This API is used to deactivate or delete multiple users in a single request. + + + +## Request + + + + + + + + + + + + + +### Request Parameters + + + + To preview the user Ids to be deleted by the request without applying the requested action set this value to `true`. + + + To Permanently delete a user from FusionAuth set this value to `true`. Once a user has been permanently deleted, the action cannot be undone. When this value is set to `false` the user is marked as inactive and the user will be unable log into FusionAuth. This action may be undone by reactivating the user. + + + The maximum number of users to delete in one call. + + You may use this parameter to process deletes in batches in order to limit individual request processing time and the number of user Ids on the response. + + + The raw JSON Elasticsearch query that is used to search for Users. The userId, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence. + + It is necessary to use the query parameter when querying against `registrations` in order to achieve expected results, as this field is defined as a [nested datatype](https://www.elastic.co/guide/en/elasticsearch/reference/6.3/nested.html) in the Elasticsearch mapping. + + + + + + + The Elasticsearch query string that is used to search for Users to be deleted. The userId, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence. + + + + + + + + + The Id of the User to delete. Repeat this parameter for each user to be deleted. The userId, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence. + + + + +### Using request body + + + + + + + +## Response + +The response for this API contains the information for the Users that were affected by the request. + + + + diff --git a/astro/src/content/docs/apis/users/change-password.mdx b/astro/src/content/docs/apis/users/change-password.mdx new file mode 100644 index 0000000000..2cf871c27a --- /dev/null +++ b/astro/src/content/docs/apis/users/change-password.mdx @@ -0,0 +1,193 @@ +--- +title: Change a User's Password +description: API documentation for the FusionAuth Change a User's Password API. +order: 17 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import Aside from 'src/components/Aside.astro'; +import DeprecatedSince from 'src/components/api/DeprecatedSince.astro'; +import InlineField from 'src/components/InlineField.astro'; +import LoginIdField from 'src/content/docs/apis/_login-id-field.mdx'; +import LoginIdTypeField from 'src/content/docs/apis/_login-id-type-field.mdx'; +import JSON from 'src/components/JSON.astro'; +import XFusionauthTenantIdHeaderAmbiguousOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-ambiguous-operation.mdx'; +import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx'; +import ChangePassPostResponseCodes from 'src/content/docs/apis/_change-pass-post-response-codes.astro'; + +This API is used to change the User's password. + +This API may be used as the second part of the [Start Forgot Password workflow](#start-forgot-password-workflow). For example, after the User is sent an email or SMS message that contains a link to a web form that allows them to update their password you will call this API with the `changePasswordId` and their updated password. If the `changePasswordId` is valid then the User's password will be updated. + +This API may also be used separately from the [Start Forgot Password workflow](#start-forgot-password-workflow) by omitting the `changePasswordId` and using the `loginId` instead. + +By default the `changePasswordId` is valid for 10 minutes after it was generated. If a `404` is returned when using the change password Id, the workflow will need to be started again to generate a new identifier. This duration can be modified using the [Tenant API](/docs/apis/tenants) or in the admin UI. + + + + + +## Request + +This usage is generally intended to be part of an email or SMS workflow and does not require authentication. The `changePasswordId` used on this API request will have been previously generated by the [Start Forgot Password workflow](#start-forgot-password-workflow) or by using the Forgot Password workflow on the FusionAuth login page. + + +### Using a change password ID + + + + + +#### Request Parameters + + + + The `changePasswordId` that is used to identify the user after the [Start Forgot Password workflow](#start-forgot-password-workflow) has been initiated. + + If this `changePasswordId` was sent via an email to the User by FusionAuth during User create in order to set up a new password, or as part of a Forgot Password request, then successful use of this identifier to change the User's password will implicitly complete Email Verification if not already verified and the Tenant configuration has enabled implicit email verification. + + + This value can still be provided on the URL segment as shown in the above example, but it is recommended you send this value in the request body instead using the changePasswordId field. If the value is provided in the URL segment and in the request body, the value provided in the request body will be preferred. + + + + + + +#### Request Body + + + + The `changePasswordId` that is used to identify the user after the [Start Forgot Password workflow](#start-forgot-password-workflow) has been initiated. + + If this `changePasswordId` was sent via an email to the User by FusionAuth during User create in order to set up a new password, or as part of a Forgot Password request, then successful use of this identifier to change the User's password will implicitly complete Email Verification if not already verified and the Tenant configuration has enabled implicit email verification. + + If the changePasswordId is provided in the URL segment and in the request body, the value provided in the request body will be preferred. + + + The User's current password. When this parameter is provided the current password will be verified to be correct. + + + The User's new password. + + + This field is marked optional because it is only required when the user has enabled two-factor authentication, and a `trustChallenge` was provided on the Two-Factor Start API request. When a user has enabled two-factor authentication this field becomes required if a `trustChallenge` was provided on the Two-Factor Start API request. When required, this value must be equal to the value provided to the Two-Factor Start API. + + + This field is marked optional, because it is only required when the user has enabled two-factor authentication. When a user has enabled two-factor authentication this field becomes required when attempting to change a password using the `changePasswordId`. + + + + + +This usage requires an API key and allows you to change any user's password if you have a unique login Id. + + +### Using a login ID + + + + + + +#### Request Body + + + + An optional Application Id. When this value is provided, it will be used to resolve an application specific email or message template if you have configured transactional notifications such as setup password, email verification and others. + + If not provided, only the tenant configuration will be used when resolving templates. + + + The User's current password. When this parameter is provided the current password will be verified to be correct. + + When this value is provided it should be in place of the `changePasswordId` request parameter. If both the `changePasswordId` and `loginId` are provided on the request, the `changePasswordId` will take precedence. + } + /> + + + The User's new password. + + + This field is marked optional because it is only required when the user has enabled two-factor authentication, and a `trustChallenge` was provided on the Two-Factor Start API request. When a user has enabled two-factor authentication this field becomes required if a `trustChallenge` was provided on the Two-Factor Start API request. When required, this value must be equal to the value provided to the Two-Factor Start API. + + + This field is marked optional, because it is only required when the user has enabled two-factor authentication. When a user has enabled two-factor authentication this field becomes required when attempting to change a password using the `changePasswordId`. + + + + + + + +This API will use a JWT as authentication. See [JWT Authentication](/docs/apis/authentication#jwt-authentication) for examples of how you can send the JWT to FusionAuth. + +A common use case for using this API with a JWT will be if you want to allow the user to change their own password. Specifically if you are attempting to perform this request in a frontend browser that cannot store an API key. + +Because changing a User's password will revoke all existing refresh tokens if you allow the user to change their password they will need to re-authenticate to stay logged into your application if you are utilizing JWTs and Refresh Tokens. + +For this reason, this API will return a `oneTimePassword` that is intended to be used programatically after a Change Password request completes to keep the user logged in and provide a better user experience. A successful login will return you a new access token (JWT) and a refresh token. This will allow you to make the change password workflow seamless to the user. + + +### Using a JWT + + + + + + +#### Request Body + + + + The User's current password. This is required when using a JWT to change your password. + + + The User's new password. + + + The user's existing refresh token. If you have access to your current refresh token, it can be provided in the request body using this parameter. If the `refresh_token` cookie also exists and is present on the request it will take precedence over this parameter. + + This parameter is used to determine if the `oneTimePassword` that is returned from this API will be eligible to request a refresh token when used by the Login API. If this parameter is not provided and no cookie is found on the request, a refresh token will not be provided on the Login response when using the returned `oneTimePassword`. + + + This field is marked optional because it is only required when the user has enabled two-factor authentication, and a `trustChallenge` was provided on the Two-Factor Start API request. When a user has enabled two-factor authentication this field becomes required if a `trustChallenge` was provided on the Two-Factor Start API request. When required, this value must be equal to the value provided to the Two-Factor Start API. + + + This field is marked optional, because it is only required when the user has enabled two-factor authentication. When a user has enabled two-factor authentication this field becomes required when attempting to change a password using the `changePasswordId`. + + + + + +## Response + + + +### Response Body + +This JSON response body will only be returned when using a `changePasswordId` parameter or a JWT to change the password. + +When calling this API with an API key no response body will be returned. + + + + A one time password that can be used as a substitute for your `loginId` and `password` on the Login API. + + + An optional object that is returned un-modified when the forgot password request is completed. This may be useful to return the user to particular state once they complete the password change. + + + + diff --git a/astro/src/content/docs/apis/users/create.mdx b/astro/src/content/docs/apis/users/create.mdx new file mode 100644 index 0000000000..bd84bdde90 --- /dev/null +++ b/astro/src/content/docs/apis/users/create.mdx @@ -0,0 +1,40 @@ +--- +title: Create a User +description: API documentation for the FusionAuth Create a User API. +order: 2 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import StandardPostResponseCodes from 'src/content/docs/apis/_standard-post-response-codes.astro'; +import UserRequestBody from 'src/content/docs/apis/_user-request-body.mdx'; +import UserResponseBody from 'src/content/docs/apis/_user-response-body.mdx'; +import XFusionauthTenantIdHeaderCreateOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-create-operation.mdx'; + +This API is used to create a new User. + +## Request + + + + + + + +### Request Parameters + + + + The Id to use for the new User. If not specified a secure random UUID will be generated. + + + + + +## Response + +The response for this API contains the User that was just created. The password, salt and other sensitive fields will not be returned on the API response. + + + + diff --git a/astro/src/content/docs/apis/users/delete.mdx b/astro/src/content/docs/apis/users/delete.mdx new file mode 100644 index 0000000000..d96b9683f3 --- /dev/null +++ b/astro/src/content/docs/apis/users/delete.mdx @@ -0,0 +1,41 @@ +--- +title: Delete a User +description: API documentation for the FusionAuth Delete a User API. +order: 5 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import JSON from 'src/components/JSON.astro'; +import StandardDeleteResponseCodes from 'src/content/docs/apis/_standard-delete-response-codes.astro'; +import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx'; + +This API is used to delete a User. You must specify the Id of the User on the URI. You can also specify whether or not the User is soft or hard deleted. A soft delete deactivates the User. A hard delete permanently deletes a User's data. + +Soft deleted users are marked as inactive but not deleted from FusionAuth. Deactivated users have their data retained but they are unable to authenticate. Users who have been deactivated can be reactivated; see [Reactivate a User](#reactivate-a-user) for more. + +The data of a User who has been hard deleted is permanently removed from FusionAuth. The User's data cannot be restored via the FusionAuth API or the administrative user interface. If you need to restore the User's data, you must retrieve it from a database backup. + +## Request + + + + +### Request Parameters + + + + The Id of the User to delete. + + + To Permanently delete a user from FusionAuth set this value to `true`. Once a user has been permanently deleted, the action cannot be undone. When this value is set to `false` the user is marked as inactive and the user will be unable log into FusionAuth. This action may be undone by reactivating the user. + + + + + +## Response + +This API does not return a JSON response body. + + diff --git a/astro/src/content/docs/apis/users/flush-search.mdx b/astro/src/content/docs/apis/users/flush-search.mdx new file mode 100644 index 0000000000..c302fa98be --- /dev/null +++ b/astro/src/content/docs/apis/users/flush-search.mdx @@ -0,0 +1,21 @@ +--- +title: Flush the Search Engine +description: API documentation for the FusionAuth Flush the Search Engine API. +order: 11 +--- +import API from 'src/components/api/API.astro'; +import StandardPostResponseCodes from 'src/content/docs/apis/_standard-post-response-codes.astro'; + +This API is used to issue a flush request to the FusionAuth Search. This will cause any cached data to be written to disk. In practice it is unlikely + you'll find a need for this API in production unless you are performing search requests immediately following an operation that modifies the index and + expecting to see the results immediately. + +## Request + + + +## Response + +The response does not contain a body. It only contains one of the status codes below. + + diff --git a/astro/src/content/docs/apis/users/forgot-password.mdx b/astro/src/content/docs/apis/users/forgot-password.mdx new file mode 100644 index 0000000000..3151b3a711 --- /dev/null +++ b/astro/src/content/docs/apis/users/forgot-password.mdx @@ -0,0 +1,128 @@ +--- +title: Start Forgot Password Workflow +description: API documentation for the FusionAuth Start Forgot Password Workflow API. +order: 15 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import Aside from 'src/components/Aside.astro'; +import DeprecatedSince from 'src/components/api/DeprecatedSince.astro'; +import InlineField from 'src/components/InlineField.astro'; +import LoginIdField from 'src/content/docs/apis/_login-id-field.mdx'; +import LoginIdTypeField from 'src/content/docs/apis/_login-id-type-field.mdx'; +import JSON from 'src/components/JSON.astro'; +import XFusionauthTenantIdHeaderAmbiguousOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-ambiguous-operation.mdx'; +import Breadcrumb from 'src/components/Breadcrumb.astro'; + +This API is used to start the forgot password workflow for a single User. + +For example, on your login form you may have a button for _Forgot your password_. This would be the API you would call to initiate the request for the user. If the email configuration is complete, the user will be sent the forgot password email containing a link containing the `changePasswordId`. The provided link should take the user to a form that allows them to change their password. This form should contain a hidden field for the `changePasswordId` generated by this API. + +By default the `changePasswordId` is valid to be used with the [Change Password](#change-a-users-password) API for 10 minutes. If a `404` is returned when using this Id to change the password, the workflow +will need to be started again to generate a new identifier. This duration can be modified using the Tenant API or in the FusionAuth UI. + +You may optionally authenticate this request with an API key to allow for some additional request parameters and the generated `changePasswordId` will be returned in the JSON body. This may be helpful if you wish to use your own email system or you have an alternative method to call the [Change Password](#change-a-users-password) API. + + + +## Request + +Calling this API without an API key always attempts to send a message to the user. If FusionAuth is unable to deliver a message based on the resolved identity and tenant configuration, a forgot password workflow will not be started. + + +### Without an API key + + + + + + +#### Request Body + + + + The Id of the application. If valid, the email or message template configured in the Application settings will be used, if present. If not present, the template configured in the Tenant settings will be used. In either case, the corresponding Application object will be available to the template. + + + + + An optional object that will be returned un-modified when you complete the forgot password request using the [Change a User's Password API](#change-a-users-password). This may be useful to return the user to particular state once they complete the password change. + + + + + + +### Using an API key + + + + + + +#### Request Body + + + + The Id of the application. If valid, the email or message template configured in the Application settings will be used, if present. If not present, the template configured in the Tenant settings will be used. In either case, the corresponding Application object will be available to the template. + + + The optional change password Id to be used on the [Change a User's Password](#change-a-users-password) API. + + It is recommended to omit this parameter and allow FusionAuth to generate the identifier. Use this parameter only if you must supply your own value for integration into existing systems. + + + + + Whether or not calling this API should attempt to send the user an email using the configured Forgot Password email template. Setting this to `false` will begin the Forgot Password workflow without sending an email and only create the `changePasswordId`, this may be useful if you want to send an email outside of FusionAuth, or complete this workflow without the use of email. + + + + Prefer using the new sendForgotPasswordMessage field. + + + Determines whether a forgot password message is sent to the user. Setting this to `true` will cause a message to be sent. Setting this to `false` will begin the Forgot Password workflow without sending a message and only create the `changePasswordId`, which may be useful if you want to send a message outside of FusionAuth, or complete this workflow without the use of email/SMS. + + The template and delivery method are based on the type of the identity resolved by the request. + + * FusionAuth will attempt to deliver the message via SMS when the provided login Id and type resolve to a phone number identity. This requires tenant.phoneConfiguration.forgotPasswordTemplateId to be configured, otherwise the request will fail. + * If the provided login Id and type resolve to an email or username identity, FusionAuth will attempt to deliver the message via email. This requires tenant.emailConfiguration.forgotPasswordEmailTemplateId to be configured, otherwise the request will fail. + + + An optional object that will be returned un-modified when you complete the forgot password request. This may be useful to return the user to particular state once they complete the password change. + + + + + +## Response + +{/* +this 'response codes' header has extra spacing, but to fix we'd have to convert the below table into a HTML table inside an astro component, like we did with astro/src/content/docs/apis/_change-pass-response-codes.astro +*/} +__Response Codes__ +|Code |Description | +| --- | --- | +|200 |The request was successful. A JSON response body will be provided when authenticated using an API key, when the API key has been omitted from the request, no response body is provided. | +|400 |The request was invalid and/or malformed. The response will contain an [Errors](/docs/apis/errors) JSON Object with the specific errors. | +|401 |You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](/docs/apis/authentication). | +|403 |The forgot password functionality has been disabled. This is caused by an administrator setting the Forgot Password Email Template to the option _Feature Disabled. No template selected._ in the Tenant Email configuration. See Tenants -> Email -> Template settings in the FusionAuth admin UI. | +|404 |The User could not be found. | +|422 |The User does not have an email address, this request cannot be completed. Before attempting the request again add an email address to the user. | +|500 |There was an internal error. A stack trace is provided and logged in the FusionAuth log files. | +|503 |The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.| | + +### Response Body + + + + The change password Id that was generated by this API request. This identifier may be used by the [Change a User's Password](#change-a-users-password) API. This field is only returned in the JSON response body if the request was authenticated using an API key, if an API key is not used no response body is returned. + + + + diff --git a/astro/src/content/docs/apis/users/import-refresh-tokens.mdx b/astro/src/content/docs/apis/users/import-refresh-tokens.mdx new file mode 100644 index 0000000000..a46ba6b2df --- /dev/null +++ b/astro/src/content/docs/apis/users/import-refresh-tokens.mdx @@ -0,0 +1,32 @@ +--- +title: Import Refresh Tokens +description: API documentation for the FusionAuth Import Refresh Tokens API. +order: 9 +--- +import API from 'src/components/api/API.astro'; +import Aside from 'src/components/Aside.astro'; +import StandardGetResponseCodes from 'src/content/docs/apis/_standard-get-response-codes.astro'; +import UsersRefreshTokensRequestBody from 'src/content/docs/apis/_users-refresh-tokens-request-body.mdx'; +import XFusionauthTenantIdHeaderCreateOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-create-operation.mdx'; + + + +This API is used to import refresh tokens from an external system, this would generally be done during an initial user import or as an auxiliary step during a migration strategy. + +Before using this API, create the Users, Applications and User Registrations. A validation error will be returned if the user does not exist, or is not registered for the application. + +## Request + + + + + + + +## Response + +The response does not contain a body, the HTTP status code will indicate the result of the request. + + diff --git a/astro/src/content/docs/apis/users/import.mdx b/astro/src/content/docs/apis/users/import.mdx new file mode 100644 index 0000000000..e92b7b1a0f --- /dev/null +++ b/astro/src/content/docs/apis/users/import.mdx @@ -0,0 +1,69 @@ +--- +title: Import Users +description: API documentation for the FusionAuth Import Users API. +order: 8 +--- +import API from 'src/components/api/API.astro'; +import ImportUsersRequestBody from 'src/content/docs/apis/_import-users-request-body.mdx'; +import InlineField from 'src/components/InlineField.astro'; +import JSON from 'src/components/JSON.astro'; +import RemoteCode from 'src/components/RemoteCode.astro'; +import StandardPostResponseCodes from 'src/content/docs/apis/_standard-post-response-codes.astro'; +import XFusionauthTenantIdHeaderCreateOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-create-operation.mdx'; + +This API is used to bulk import multiple Users into FusionAuth. Each User must have at least an **email** or a **username**, and a **password** (plaintext or hash). If you don't have the User's password, you can set this field to a long random string and require the User to reset their password at their next login. This request is useful for migrating data from an existing database into FusionAuth. Additionally, you can provide an Id for each User inside the JSON User object of the request body. When using this API, the recommended batch size per request is dependent on deployment scale (note: 100,000 users per request is a reasonable batch size for a production capable deployment). After completing an import, you should [reindex the Elasticsearch database](/docs/lifecycle/manage-users/search#reindexing-elasticsearch) as well. + +You should not make multiple calls to this API in parallel. Multiple sequential calls to this API are fine. + +## Request + + + + + + + +## Response + +Only a status code is available on the Import API, no JSON body will be returned. + + + + +## Password Hashes + +Password hashes can be imported into FusionAuth. This allows users to transparently use their old passwords while at no time exposing the plaintext password. This section contains details about importing specific password hashes. + +You can also learn more about hashes in the [password hashing reference](/docs/reference/password-hashes), and you can [implement your own custom hash](/docs/extend/code/password-hashes/custom-password-hashing) as well. + +## Encoding + +The standard FusionAuth password hashing schemes require the password hash to be a base64 encoded string. If your password hashes are encoded in a different format, they will need to either be converted and imported as base64, or you can create a custom plugin using an alternative encoding. You can see an example of converting below. + +It is recommended to use a base64 encoded string, but if importing hashes from a legacy system that uses base16, base32, or another encoding, import the hash in the same format the plugin produces. + + + +## Bcrypt + +When importing a bcrypt hash, you may have a value such as: + +`$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy` + +This single string represents the bcrypt version, factor, salt and hash. + +The number before the final `$` is the factor, the 22 characters after the final `$` is the salt and the last 31 characters are the hash. + +For the above bcrypt hash, `10` is the factor and should be placed in the factor field. `N9qo8uLOickgx2ZMRZoMye` is the salt and should be placed in the salt field. `IjZAgcfl7p92ldGxad68LJZdL17lhWy` is the hash value and should be placed in the password field. + +## MD5 + +When importing an MD5 password hash, you may not have a salt. If this is the case, use the empty string, `''`, as the salt. You may still use the salted MD5 plugin provided by FusionAuth. + +MD5 is commonly stored in hexadecimal format, such as `25d55ad283aa400af464c76d713c07ad`. The FusionAuth Import Users API requires imported password hashes to be base64 encoded. Convert any hexadecimal values to base64 before importing, or the import will not work. + +Here is an example ruby script to convert hexadecimal values to base64 encoded: + + diff --git a/astro/src/content/docs/apis/users/index.mdx b/astro/src/content/docs/apis/users/index.mdx new file mode 100644 index 0000000000..96eaac8bb3 --- /dev/null +++ b/astro/src/content/docs/apis/users/index.mdx @@ -0,0 +1,26 @@ +--- +title: User API +description: Learn how to integrate with the FusionAuth User API. This documentation provides a comprehensive reference for managing users. +order: 1 +--- + +This page contains all of the APIs for managing users. + +| Operation | Method | Endpoint | +|---|---|---| +| [Create a User](/docs/apis/users/create) | `POST` | `/api/user` | +| [Retrieve a User](/docs/apis/users/retrieve) | `GET` | `/api/user` | +| [Update a User](/docs/apis/users/update) | `PUT` | `/api/user/{userId}` | +| [Delete a User](/docs/apis/users/delete) | `DELETE` | `/api/user/{userId}` | +| [Bulk Delete Users](/docs/apis/users/bulk-delete) | `DELETE` | `/api/user/bulk` | +| [Reactivate a User](/docs/apis/users/reactivate) | `PUT` | `/api/user/{userId}?reactivate=true` | +| [Import Users](/docs/apis/users/import) | `POST` | `/api/user/import` | +| [Import Refresh Tokens](/docs/apis/users/import-refresh-tokens) | `POST` | `/api/user/refresh-token/import` | +| [Search for Users](/docs/apis/users/search) | `GET` / `POST` | `/api/user/search` | +| [Flush the Search Engine](/docs/apis/users/flush-search) | `PUT` | `/api/user/search` | +| [Retrieve Recent Logins](/docs/apis/users/recent-logins) | `GET` | `/api/user/recent-login` | +| [Verify a User's Email](/docs/apis/users/verify-email) | `POST` | `/api/user/verify-email` | +| [Resend Verification Email](/docs/apis/users/resend-verification) | `PUT` | `/api/user/verify-email` | +| [Start Forgot Password Workflow](/docs/apis/users/forgot-password) | `POST` | `/api/user/forgot-password` | +| [Validate a Password Change](/docs/apis/users/validate-password-change) | `GET` | `/api/user/change-password` | +| [Change a User's Password](/docs/apis/users/change-password) | `POST` | `/api/user/change-password` | diff --git a/astro/src/content/docs/apis/users/reactivate.mdx b/astro/src/content/docs/apis/users/reactivate.mdx new file mode 100644 index 0000000000..d5f739bd26 --- /dev/null +++ b/astro/src/content/docs/apis/users/reactivate.mdx @@ -0,0 +1,35 @@ +--- +title: Reactivate a User +description: API documentation for the FusionAuth Reactivate a User API. +order: 7 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import StandardPutResponseCodes from 'src/content/docs/apis/_standard-put-response-codes.astro'; +import UserResponseBody from 'src/content/docs/apis/_user-response-body.mdx'; +import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx'; + +This API is used to reactivate an inactive Users. You must specify the Id of the User on the URI. + +## Request + + + +### Request Parameters + + + + The Id of the User to reactivate. + + + + + +## Response + +The response for this API contains the information for the User that was reactivated. + + + + diff --git a/astro/src/content/docs/apis/users/recent-logins.mdx b/astro/src/content/docs/apis/users/recent-logins.mdx new file mode 100644 index 0000000000..f007bd1a6a --- /dev/null +++ b/astro/src/content/docs/apis/users/recent-logins.mdx @@ -0,0 +1,106 @@ +--- +title: Retrieve Recent Logins +description: API documentation for the FusionAuth Retrieve Recent Logins API. +order: 12 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import Aside from 'src/components/Aside.astro'; +import JSON from 'src/components/JSON.astro'; +import EnterprisePlanBlurbApi from 'src/content/docs/_shared/_enterprise-plan-blurb-api.astro'; +import StandardGetResponseCodes from 'src/content/docs/apis/_standard-get-response-codes.astro'; + + + +This API is used to retrieve recent logins. + +## Request + + + +### Request Parameters + + + + This parameter indicates the maximum amount of logins to return for a single request. + + + This parameter provides the offset into the result set. Generally speaking if you wish to paginate the results, you will increment this parameter on subsequent API request by the size of the `limit` parameter. + + + This parameter will narrow the results to only logins for a particular user. When this parameter is omitted, the most recent logins for all of FusionAuth will be returned. + + + +## Response + +The response will contain recent logins containing no more than the value set by the `limit` parameter. By design, this API does not return the total number of results and only lets paginate through the results from newest to oldest. + + + +### Response Body + + + + A list of recent logins. + + + The unique Id of the application that is represented by this login record. + + + The name of the application at the time this record was created. + + + The [instant](/docs/reference/data-types#instants) this login occurred. + + + The IP address if provided during the login request. + + + The city where the login request originated. + + + + + + The country where the login request originated. + + + + + + The latitude where the login request originated. + + + + + + The longitude where the login request originated. + + + + + + The geographic location where the login request originated. + + + + + + The zipcode where the login request originated. + + + + + + The User's email address or username at the time of the login request. + + + The unique Id of the user that is represented by this login record. + + + + diff --git a/astro/src/content/docs/apis/users/resend-verification.mdx b/astro/src/content/docs/apis/users/resend-verification.mdx new file mode 100644 index 0000000000..f8790a7852 --- /dev/null +++ b/astro/src/content/docs/apis/users/resend-verification.mdx @@ -0,0 +1,86 @@ +--- +title: Resend Verification Email +description: API documentation for the FusionAuth Resend Verification Email API. +order: 14 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import InlineField from 'src/components/InlineField.astro'; +import JSON from 'src/components/JSON.astro'; +import PremiumPlanBlurbApi from 'src/content/docs/_shared/_premium-plan-blurb-api.astro'; +import StandardPutResponseCodes from 'src/content/docs/apis/_standard-put-response-codes.astro'; +import XFusionauthTenantIdHeaderAmbiguousOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-ambiguous-operation.mdx'; + +This API is used to resend the verification email to a User. This API is useful if the User has deleted the email, or the verification Id has expired. By default, the verification Id will expire after 24 hours. You can modify this duration in the Tenant settings. + +## Request + + +### Without an API key + + + + +#### Request Parameters + + + + The Id of the application. If valid, the email or message template configured in the Application settings will be used, if present. If not present, the template configured in the Tenant settings will be used. In either case, the corresponding Application object will be available to the template. + + + The email address used to uniquely identify the User. + + + + + + +### Using an API key + + + + +#### Request Parameters + + + + The Id of the application. If valid, the email or message template configured in the Application settings will be used, if present. If not present, the template configured in the Tenant settings will be used. In either case, the corresponding Application object will be available to the template. + + + The email address used to uniquely identify the User. + + + If you would only like to generate a new verificationId and return it in the JSON body without FusionAuth attempting to send the User an email + set this optional parameter to `false`. + + This may be useful if you need to integrate the Email Verification process using a third party messaging service. + + + + + +## Response + +When authenticated using an API key a response body will be provided. If an API key was not used to authenticate the request no body is returned. + + + +### Response Body + + + + The email verification Id that was generated by this API request. This identifier may be used by the [Verify a User's Email](#verify-a-users-email) API. + This field is only returned in the JSON response body if the request was authenticated using an API key, if an API key is not used no response body is returned. + + + Depending on your tenant configuration, this may be returned. The verification One Time Code is used with the gated Email Verification workflow. The user enters this code to verify their email. + + + + + + + + + diff --git a/astro/src/content/docs/apis/users/retrieve.mdx b/astro/src/content/docs/apis/users/retrieve.mdx new file mode 100644 index 0000000000..ea51fe5b1e --- /dev/null +++ b/astro/src/content/docs/apis/users/retrieve.mdx @@ -0,0 +1,130 @@ +--- +title: Retrieve a User +description: API documentation for the FusionAuth Retrieve a User API. +order: 3 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import LoginIdField from 'src/content/docs/apis/_login-id-field.mdx'; +import LoginIdTypeField from 'src/content/docs/apis/_login-id-type-field.mdx'; +import StandardGetResponseCodes from 'src/content/docs/apis/_standard-get-response-codes.astro'; +import UserResponseBody from 'src/content/docs/apis/_user-response-body.mdx'; +import XFusionauthTenantIdHeaderAmbiguousOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-ambiguous-operation.mdx'; +import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx'; + +This API is used to retrieve the information about a single User. You can use the User's Id, username or email address to retrieve the User. The Id is specified on the URI and the username or email are specified as URL parameters. + +## Request + + +### By user ID + + + +#### Request Parameters + + + + The unique Id of the User to retrieve. + + + + + + +### By login ID + + + +#### Request Parameters + + + + The unique Id of the User to retrieve. The loginId can be either the email or username. + + + + + + +### By login ID and type + + + +#### Request Parameters + + + + + + + + + +### By email + + + +#### Request Parameters + + + + The email of the User to retrieve. + + + + + + +### By username + + + +#### Request Parameters + + + + The username of the User to retrieve. + + + + + + +### By change password ID + + + +#### Request Parameters + + + + The change password Id associated with the user when the Forgot Password workflow has been started. + + + + + + +### By verification ID + + + +#### Request Parameters + + + + The verification Id associated with the user when the Email or Phone number verification process has been started. + + + + + +## Response + +The response for this API contains the User. + + + + diff --git a/astro/src/content/docs/apis/users/search.mdx b/astro/src/content/docs/apis/users/search.mdx new file mode 100644 index 0000000000..6a7a5828ab --- /dev/null +++ b/astro/src/content/docs/apis/users/search.mdx @@ -0,0 +1,96 @@ +--- +title: Search for Users +description: API documentation for the FusionAuth Search for Users API. +order: 10 +--- +import API from 'src/components/api/API.astro'; +import Aside from 'src/components/Aside.astro'; +import JSON from 'src/components/JSON.astro'; +import StandardGetResponseCodes from 'src/content/docs/apis/_standard-get-response-codes.astro'; +import UserSearchRequestBodyDatabaseExamples from 'src/content/docs/apis/_user-search-request-body-database-examples.mdx'; +import UserSearchRequestBodyElasticsearchExamples from 'src/content/docs/apis/_user-search-request-body-elasticsearch-examples.mdx'; +import UserSearchRequestParameters from 'src/content/docs/apis/_user-search-request-parameters.mdx'; +import UsersResponseBody from 'src/content/docs/apis/_users-response-body.mdx'; +import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx'; + +This API is used to search for Users. +This API may be called using the `GET` or `POST` HTTP methods, examples of each are provided below. +The `POST` method is provided to allow for a richer request object without worrying about exceeding the maximum length of a URL. +Calling this API with either the `GET` or `POST` HTTP method will provide the same search results given the same query parameters. + +## Request + +Which search query parameters are available and how they behave depends on the search engine type. Read more about [the different types of search engines](/docs/get-started/core-concepts/users#user-search). + +## Database Search Engine + +This is a good choice for [smaller installs, embedded scenarios, or other places where the additional capability of Elasticsearch is not required](/docs/get-started/core-concepts/users#database-search-engine). + + + + + + + + + + +### Request Parameters + + + + + + + + + +### Request Body + + + +#### Request Body Examples + + + +## Elasticsearch Search Engine + +The Elasticsearch engine has [advanced querying capabilities and better performance](/docs/get-started/core-concepts/users#elasticsearch-search-engine). You can also review the [Elasticsearch search guide](/docs/lifecycle/manage-users/search/user-search-with-elasticsearch) for more examples. + + + + + + + + + + + +### Request Parameters + + + + + + + + + +### Request Body + + + +#### Request Body Examples + + + +## Response + +The response contains the User objects that were found as part of the lookup or search. Both the database and Elasticsearch search engines return the response in the same format. + + + + diff --git a/astro/src/content/docs/apis/users/update.mdx b/astro/src/content/docs/apis/users/update.mdx new file mode 100644 index 0000000000..84cfc0fca5 --- /dev/null +++ b/astro/src/content/docs/apis/users/update.mdx @@ -0,0 +1,41 @@ +--- +title: Update a User +description: API documentation for the FusionAuth Update a User API. +order: 4 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import GenericUpdateExplanationFragment from 'src/content/docs/apis/_generic-update-explanation-fragment.mdx'; +import StandardPutResponseCodes from 'src/content/docs/apis/_standard-put-response-codes.astro'; +import UserRequestBody from 'src/content/docs/apis/_user-request-body.mdx'; +import UserResponseBody from 'src/content/docs/apis/_user-response-body.mdx'; +import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx'; + + + +If you specify a new password for the User, it will be encrypted and stored. However, if you do not provide a new password, the User's old password will be preserved. This is the only field that is merged during an update using the `PUT` method. + +## Request + + + +### Request Parameters + + + + The Id of the User to update. + + + + + + + +## Response + +The response for this API contains the User that was updated. The password hash and other sensitive fields are never returned on the API response. + + + + diff --git a/astro/src/content/docs/apis/users/validate-password-change.mdx b/astro/src/content/docs/apis/users/validate-password-change.mdx new file mode 100644 index 0000000000..8abc3bca64 --- /dev/null +++ b/astro/src/content/docs/apis/users/validate-password-change.mdx @@ -0,0 +1,103 @@ +--- +title: Validate a password change +description: API documentation for the FusionAuth Validate a password change API. +order: 16 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import Aside from 'src/components/Aside.astro'; +import LoginIdField from 'src/content/docs/apis/_login-id-field.mdx'; +import LoginIdTypeField from 'src/content/docs/apis/_login-id-type-field.mdx'; +import LoginMetadataDevice from 'src/content/docs/apis/_login-metadata-device.mdx'; +import JSON from 'src/components/JSON.astro'; +import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx'; +import ChangePassGetResponseCodes from 'src/content/docs/apis/_change-pass-get-response-codes.astro'; + +## Request + +This API is used to validate whether a request to [change a user's password](#change-a-users-password) will require MFA (via a `trustToken`). There are 3 ways to call the endpoint: +1. Validate a `changePasswordId` without authentication +2. Validate user password change using a JWT +3. Validate user password change using a `loginId` with API key + +The first case will also verify that a `changePasswordId` is valid. This usage is generally intended to be part of an email or SMS workflow and does not require authentication. The `changePasswordId` used on this API request will have been previously generated by the [Start Forgot Password API](#start-forgot-password-workflow) or by using the Forgot Password workflow on the FusionAuth login page. Use this API to validate the `changePasswordId` before requesting a password change. + + +### Using a change password ID + + + + +#### Request Parameters + + + + The `changePasswordId` that is used to identify the user after the [Start Forgot Password workflow](#start-forgot-password-workflow) has been initiated. + + + The IP address of the end-user that is changing their password. If this value is omitted FusionAuth will attempt to obtain the IP address of + the client, the value will be that of the `X-Forwarded-For` header if provided or the last proxy that sent the request. This value may be used by an MFA requirement lambda to determine if multi-factor authentication should be required. + + + + + + + +The "Validate user password change using a JWT or `loginId`" cases are used to verify whether MFA is required to change a user's password based solely on the user's JWT or `loginId`. It does not validate a specific `changePasswordId` and is instead meant to validate whether MFA is required before [changing the user's password](#change-a-users-password) using a JWT or `loginId`. + + +### Using a JWT + + + + +#### Request Parameters + + + + The IP address of the end-user that is changing their password. If this value is omitted FusionAuth will attempt to obtain the IP address of + the client, the value will be that of the `X-Forwarded-For` header if provided or the last proxy that sent the request. This value may be used by an MFA requirement lambda to determine if multi-factor authentication should be required. + + + + + + +### Using a login ID + + + + +#### Request Parameters + + + + + + The IP address of the end-user that is changing their password. If this value is omitted FusionAuth will attempt to obtain the IP address of + the client, the value will be that of the `X-Forwarded-For` header if provided or the last proxy that sent the request. This value may be used by an MFA requirement lambda to determine if multi-factor authentication should be required. + + + + + + + +## Response + +This JSON response body will only be returned when a validation error occurs. + +A successful response will not contain a response body. + + diff --git a/astro/src/content/docs/apis/users/verify-email.mdx b/astro/src/content/docs/apis/users/verify-email.mdx new file mode 100644 index 0000000000..585f0d3afb --- /dev/null +++ b/astro/src/content/docs/apis/users/verify-email.mdx @@ -0,0 +1,82 @@ +--- +title: Verify a User's Email +description: API documentation for the FusionAuth Verify a User's Email API. +order: 13 +--- +import APIBlock from 'src/components/api/APIBlock.astro'; +import APIField from 'src/components/api/APIField.astro'; +import API from 'src/components/api/API.astro'; +import Aside from 'src/components/Aside.astro'; +import DeprecatedSince from 'src/components/api/DeprecatedSince.astro'; +import InlineField from 'src/components/InlineField.astro'; +import StandardPutResponseCodes from 'src/content/docs/apis/_standard-put-response-codes.astro'; +import XFusionauthTenantIdHeaderScopedOperation from 'src/content/docs/apis/_x-fusionauth-tenant-id-header-scoped-operation.mdx'; +import Breadcrumb from 'src/components/Breadcrumb.astro'; + +This API is used to mark a User's email as verified. This is usually called after the User receives the verification email after they register and they click the link in the email. To verify a User's phone number identity, see the [Identity Verify API](/docs/apis/identity-verify). + +## Request + + +### Using a verification ID + + + + + +#### Request Parameters + + + + The verification Id generated by FusionAuth used to verify the User's registration is valid by ensuring they have access to the provided email address. + + + This value can still be provided on the URL segment as shown in the above example, but it is recommended you send this value in the request body instead using the verificationId field. If the value is provided in the URL segment and in the request body, the value provided in the request body will be preferred. + + + + +#### Request Body + + + + The short code used to verify the User's account is valid by ensuring they have access to the provided email address. This field is required when the email verification strategy on the Tenant is set to `Form field`. + + + The verification Id generated by FusionAuth used to verify the User's account is valid by ensuring they have access to the provided email address. + + When using the `Form field` strategy for Email verification, this value is used along with the `oneTimeCode` as a pair to verify the email address. + + If the verificationId is provided in the URL segment and in the request body, the value provided in the request body will be preferred. + + + + + + + +This API can be used to mark a user as verified without requiring the user to actually complete a verification process. + + +### Administratively + + + + +#### Request Body + + + + The unique Id of the user to mark verified. + + + +## Response + +The response does not contain a body. It only contains one of the status codes below. + + + The verify email functionality has been disabled. See Tenants -> Email -> Email verification settings in the FusionAuth admin UI. +