Manage user accounts: Reader experience

Arc XP Identity provides a SDK package (and public APIs) to manage common activities performed by end-users (i.e. readers) when interacting with the site. This page will walk you through use cases using the SDK methods and/or Arc XP Identity public APIs.

The most important functionalities are provided through Arc XP Identity Theme blocks, allowing many features to be used immediately with minimal configuration and without the need for additional development work.

Note

You can distinguish public APIs because they contain a /public/ as part of the endpoint. As we mention in How-to Connect and log in with Arc XP Identity SDKs and APIs on the web the most of our SDK methods are wrapping calls to public APIs.

As part of some updates, Arc XP Identity streams relevant events via WebSocket, see How-to listen Web Socket events and Implement IFX email service provider for additional details.

Prerequisites

• Check the How-to Connect and log in with Arc XP Identity SDKs and APIs on the web guide.
• Know the API Origin or CDN. The CDN endpoint has the following format:
  • https://[orgName]-[siteName]-[env].api.arc-cdn.net

If you are using the SDK package, you will need to import the library on each file you are using it. All the methods will be found on the Identity object.

Example

import Identity from '@arc-publishing/sdk-identity';
...
    await Identity.getConfig().then(config => {
          ...
    });

View tenant settings

There are a lot of configurations that can be customized per tenant (organization+site). For example:

• Third authentication providers: Facebook, Google, Apple, OIDC.
• Pasword requirements.
• reCAPTCHA settings.

You may need to retrieve these settings from the site to enable flows or validations.

SDK Method	API
getConfig()	GET /identity/public/v1/config

User Sign up

Sign up with email and password

The end-user should be enforced to provide an email (and/or username) and password during Sign up. The password must meet the minimum password requirements. Additional user account information, such as first name, last name, second last name, birth date, etc., may also be requested.

SDK Method	API
signUp()	POST /identity/public/v1/signup

If the Sign up is successful, USER_SIGN_UP and VERIFY_EMAIL events are created.

If the email verification flag is ON, the user must verify their email before they can log into the system. Otherwise, when the flag is OFF, the account is created and the user is automatically logged in without needing to verify their email.

Additional details

• Implement registration, login and one-time-access link

Sign up with a third authentication provider

Implementing social sign-in options allows users to create accounts without needing to remember additional passwords. Depending on the third-party authentication provider, different SDK methods (and/or APIs) are provided.

Third-party	SDK Method	API
Google	signInWithGoogle()	POST /identity/public/v1/auth/login
Facebook	initFacebookLogin() facebookSignOn()	NA POST /identity/public/v1/auth/login
Apple	initAppleSignOn() appleSignOn()	GET /identity/public/v1/apple/authurl POST /identity/public/v1/auth/login
OIDC	initiateOIDC() signInWithOIDC()	GET /identity/public/v2/oidc/${oidcClientId}/initiate GET /identity/public/v2/oidc/signin?${params}
	socialLogin()	POST /identity/public/v1/auth/login
signInWithGoogle(), facebookSignOn() and appleSignOn() internally call socialLogin(). initFacebookLogin() initialize the FB SDK library and getFacebookLoginStatus() calls FB.getLoginStatus

An account created using a third-party authentication provider is set as verified by default. If the Sign up is successful, a USER_SIGN_UP event is created.

Additional details

• Implement social Sign In
• Implement social Sign in using OIDC: Apple

User login

Once the user ask for log in, if the response to the request is successful, regardless of the authentication type, Arc XP Identity returns and access-token and a refresh-token. These token as used to authenticate and track the user’s calls to protect public APIs.

Login with email and password

Basic credentials are provided by the end-user in order to get access to the system: email (or username) and password.

SDK Method	API
login()	GET /identity/public/v1/auth/login

Additional details

• Implement registration, login and one-time-access link

Login with a third authentication provider

The methods and APIs involved are the same provided on Sign up with a third authentication provider section.

Login with one-time-access link

Sometimes, users can’t recall their password (or don’t have access to their password keeper) but want to log in without going through the password reset process. Passwordless authentication allows users to authenticate without the need to login with a password. With this form of authentication, users are presented with the option of logging in simply via a one-time-access link, which in turn uses a nonce (i.e. token) that is delivered via email.

SDK Method	API
requestOTALink()	POST /identity/public/v1/auth/magiclink
redeemOTALink()	GET /identity/public/v1/auth/magiclink/${nonce}

Once the end-user requests the OTA link, a MAGIC_LINK_SEND event is dispatched. The event contains a nonce, which must be shared with the user via an email service provider. The nonce is valid for 24 hours and can be redeemed only once. Once redeemed, a user session is created. The refresh-token issued with the user session will also be valid for 24 hours.

Additional details

• Implement registration, login and one-time-access link

Extend session

Every time a user session is started, two JWTs are returned: access-token and refresh-token. The access token validates the active user session, but it has a default time-to-live (TTL) of 15 minutes. To maintain an active session, the access token must be refreshed by obtaining a new one every 15 minutes.

SDK Method	API
extendSession()	POST /identity/public/v1/auth/token
isLoggedIn()	POST /identity/public/v1/auth/token It calls extendSession() only if access-token is expired and refresh-token is still valid

By default, all our SDK methods that require authentication are responsible for refreshing the session, if needed, before proceeding with any call.

Unlink identity

A user account could have multiple identities attached. The end-user can unlink an identity, but you must ensure that the unlink option is available only if the user account has more than one identity.

Depending on whether the identity was created using Facebook, Google, Apple, or a third-party through OIDC, you will need to use a different SDK method (or API).

SDK Method	API
UnlinkSocialIdentity()	DELETE /identity/public/v1/identity/${grantType}
unlinkOIDC()	PUT /identity/public/v2/oidc/unlink

View and update user profile

The end user can view and update different parameters of their account. Ensure that the form you provide to the end user applies the same parameter validations that exist in our system.

SDK Method	API
getUserProfile()	GET /identity/public/v1/profile
updateUserProfile()	PATCH /identity/public/v1/profile
NA	PUT /identity/public/v1/profile

Every time the profile is updated, a PROFILE_EDIT event is dispatched.

Verify email

If the email is not verified, the end user will need to go through two steps in order to get this verify it. Depending on the verify email setting, verification may be required before the user can access to the system.

• Request an email verification. This will create a VERIFY_EMAIL event. If you just asked for sign up using email (or username) and password, this request is created automatically. The event will contain a nonce, which will be valid for 24 hour and can be used for the user to verify the account. The nonce must be shared with the user via an email service provider.

• Verify email. The user will need to use the nonce shared to verify the email. If the email is verified, a EMAIL_VERIFIED event will be created.

SDK Method	API
requestVerifyEmail()	POST /identity/public/v1/email/verify
verifyEmail()	GET /identity/public/v1/email/verify/${nonce}

Password reset

The end user can request a password update in two ways:

Cannot remember the password

In this case, the user must first request a password reset. This request will create a PASSWORD_RESET_REQUEST event, which contains a nonce. The nonce should be shared to the user via an email service provider. Then, the user can use the nonce to set a new password for their account.

The nonce should be shared as a link, and that link should take the user to the form where they can enter their new password. When submitting the form, the nonce and the new password will be passed. If the nonce is valid and the new password meets the minimum password requirements, the new password will be set for the account, a PASSWORD_RESET event is created, and the user will be able to acess to their account using the new password.

SDK Method	API
requestVerifyEmail()	POST /identity/public/v1/password/reset
verifyEmail()	GET /identity/public/v1/email/verify/${nonce}

The nonce created for the PASSWORD_RESET_REQUEST event is valid for 24 hours. Once it expires, the user will need to request a new one. The nonce can be validated by calling GET /identity/public/v1/password/{nonce}/validate

Updating password for logged in user

In this case, the user is already logged into the system and remembers their current password. A form where the user is forced to put the current and the new password must be provided to the user. If both, current and new passwords are valid, the new password is set to the user account and a PASSWORD_RESET event is created.

SDK Method	API
updatePassword()	PUT /identity/public/v1/password

In both cases, ensure that the new password entered by the user meets the minimum password requirements before send the form, and provide all necessary information about these requirements to the user.

Account deletion

The user can request their account deletion. Before proceeding with this process, if the tenant has subscriptions enabled, all subscriptions should be terminated first. The account deletion involves two steps:

• Request delete account. This will create an ANONYMIZE_USER_DELETION_REQUESTED event, and mark the account for deletion, placing it in a status of waiting for approval to be deleted. The event will contain a nonce, which must be used for the user to approve or decline the account deletion. The nonce should be shared with the user via an email service provider.

• Approve or reject the account deletion. The user must use the nonce to approve or decline the account deletion.

If the user declines the account deletion, a reason (which could be one of ‘MISTAKE’, ‘CHANGED_MIND’, ‘OTHER’, or ‘DID_NOT_REQUEST_DELETION’) should be sent as part of the request, and an ACCOUNT_DELETION_REQUEST_DECISION event will be created.

If the user approves the deletion, an ACCOUNT_DELETION_REQUEST_COMPLETED event is created once it’s successful, the user’s Profile, Identity, User, Address, Payment, and Subscription records will be deleted for Arc XP.

SDK Method	API
requestDeleteAccount()	DELETE /identity/public/v1/user/anonymize
approveDeleteAccount()	PUT /identity/public/v1/user/anonymize/approve/{nonce}
declineDeleteAccount()	PUT /identity/public/v1/user/anonymize/decline/{nonce}

Log out

A logout option should be provided to the user, this option invalidates the current access-token and refresh-token, preventing the user from making further requests to the system on their behalf.

SDK Method	API
logout()	DELETE /identity/public/v1/auth/token