How-to Connect and log in with Arc XP Identity SDKs and APIs on the web

We provide a set of APIs and SDK methods that allow you to connect your end users with our system. For tracking user calls and accessing protected public APIs, most of our public APIs requires an access token. This access token is in JWT (JSON web tokens) format and is returned after the user is logged in to the system.

When the user logs in, two JWTs are returned if the request is successful:

• Access token: This token has a limited lifetime (15 minutes by default) and identifies the user. It must be passed as a Bearer token in the protected request.

• Refresh token: This token is used to refresh and obtain a new access token when the old one expires. You can customize the lifetime of the refresh token through the CSR tool.

To interact with our system, you can either call the APIs directly or use our SDK packages. Our SDK methods act as wrappers that help developers interact with our APIs more easily. We strongly recommend using our SDKs, as these libraries handle various tasks for you. For more details, see the following table:

	PROS	CONS
API	They are just endpoints that you interact with directly. You can use APIs with different programming languages and environments, which can be beneficial if you need to integrate with a variety of systems.	You must handle many of the lower-level details yourself, such as: Authentication: check the access-token and refresh it every 15 minutes before make additional calls Error handling Data formatting
SDK	Our SDK packages are developed with TypeScript, providing strong typing and enhanced code quality. Some functionalities are only available with SDKs (and do not have corresponding APIs). These were designed to simplify certain integrations	Our SDK methods are designed to be used with Javascript. If you are using a different language, it will not work for you. While SDKs simplify usage, they also abstract away some of the details, which might limit your control over specific aspects of the service

Note

Before starting, Subscriptions app and the API Origin (or CDN) should be configured for each tenant (organization+site). Subscriptions team is on charge to set up the Subscriptions app, and Delivery team is on charge to configure the Api Origin and CDN.

The CDN endpoint has the following format:

• https://{orgName}-{siteName}-{env}.api.arc-cdn.net

Pros of using Arc XP Identity SDKs

• We support local storage and session storage, and we handle the user account information for you. This is defined when a user asks for login by passing the rememberMe option.
• Our SDK provides easy access to several objects, and these objects contain useful information about the tenant (org and site) settings and the current user account:
  • configOptions: settings defined by the tenant and accessed after the call to Identity.getConfig()
  • userIdentity: user session information, access token, refresh token, and UUID. This information is returned by calling Identity.login()
  • userProfile: user profile information, which contains information returned by Identity.getUserProfile(), and keeps this information on sync after updates.

Using Identity from a public domain through APIs

All available public APIs are documented in our Open API documentation. You can identify these APIs by the presence of /identity/public/ in the endpoint URL. Some of these APIs do not require authentication. However, for those that do require authentication, you must pass a valid access_token (Authorization header). Ensure the access token is valid before making the API call.

Example: No authentication required

curl --location 'https://{ApiOrigin|CDN}/identity/public/v1/config'

Example: Authentication required

curl --location 'https://{ApiOrigin|CDN}/identity/public/v1/profile' \
--header 'Authorization: Bearer {access_token}'

For more information about the available APIs, see Arc XP Subscriptions APIs.

Using Identity from a public domain through the SDK

The Arc XP Identity SDK is published to NPM.

After you install npm, to install the Arc SDKs, execute the following command in your npm project:

npm i @arc-publishing/sdk-identity

After you have them installed, include the SDKs in your code:

import Identity from '@arc-publishing/sdk-identity';

To access the right API endpoints through the SDKs, specify an API Origin before calling any other SDK methods.

Identity.options({
apiOrigin: '{your api origin or CDN here}'
});

Note

If you are using Page Builder, you can set up the API origin directly on the code (blocks.json file) or through the Page Builder app (Site Properties tab). Check How-to: ArcXP Identity Themes Blocks Configuration & Customization Deep Dive for additional information. If you are using our blocks, we call Identity.options() for you.

For more information about the available SDK methods, see Arc XP Subscriptions SDKs.

Arc XP Identity SDKs and APIs

As mentioned earlier, most of our SDK methods serve as wrappers, making it easier for developers to interact with our APIs. The following table lists the Identity SDK methods and the corresponding APIs they wrap, where applicable:

SDK Method	API
appleSignOn()	POST /identity/public/v1/auth/login
clearSession()	N/A
extendSession()	POST /identity/public/v1/auth/token
facebookSignOn()	N/A
getConfig()	GET /identity/public/v1/config
getFacebookLoginStatus()	N/A
getGdprReport()	GET /identity/public/v1/gdpr/${id}
getSwgAccessToken()	GET /identity/public/v1/swg/accesstoken
getUserProfile()	GET /identity/public/v1/profile
getUserSegments()	GET /identity/public/v2/identity/segmentation
googleSignOn()	N/A
initAppleSignOn()	GET /identity/public/v1/apple/authurl
initFacebookLogin()	N/A
initiateOIDC()	GET /identity/public/v2/oidc/${oidcClientId}/initiate
listGdprReports()	GET /identity/public/v1/gdpr?_=${Date.now()}
login()	GET /identity/public/v1/auth/login
isLoggedIn()	N/A
loginWithArcIdentityAsOIDCProvider()	GET /identity/public/v2/oidc/provider/login
logout()	DELETE /identity/public/v1/auth/token
redeemOTALink()	GET /identity/public/v1/auth/magiclink/${nonce}
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}
requestOTALink()	POST identity/public/v1/auth/magiclink
requestResetPassword()	POST /identity/public/v1/password/reset
requestVerifyEmail()	POST /identity/public/v1/email/verify
resetPassword()	PUT /identity/public/v1/password/reset/${nonce}
signInWithGoogle()	N/A
signInWithOIDC()	N/A
signInWithOIDCPKCE()	POST /identity/public/v2/oidc/provider/token
signUp()	POST /identity/public/v1/signup
socialLogin()	POST /identity/public/v1/auth/login
unlinkOIDC()	PUT /identity/public/v2/oidc/unlink
UnlinkSocialIdentity()	DELETE /identity/public/v1/identity/${grantType}
updatePassword()	PUT /identity/public/v1/password
updateUserProfile()	PATCH /identity/public/v1/profile
verifyEmail()	GET /identity/public/v1/email/verify/${nonce}