Manage user accounts: Developer interface

Arc XP Identity provides developer APIs to manage common activities that need to be automated for users by clients or to connect to other systems. This page will walk you through use cases using the Arc XP Subscriptions Identity develop APIs. It’s important note that not all the actions described on this page are allowed for all sign in providers. For example, some actions like User Sign Up and Reset Password will only work if you have provisioned a sign in provider type of password. They won’t work if your organization is using the social sign in providers, like google,facebook, or apple.

Note

You can distinguish developer APIs because they contain an /api/ as part of the endpoint.

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

• Know the base_URL, where org is your organization id.
  • api.sandbox.{org}.arcpublishing.com (for sandbox environment)
  • api.{org}.arcpublishing.com (for production environment)
• You will need a token for either the production or sandbox environment, as appropriate: ARC_ACCESS_TOKEN (see Developer Token which can be configured in Developer Center).
• Some developers APIs are site-specific and require you to pass the Arc-Site header.

Example

  curl --location --request GET 'https://{base_URL}/identity/api/v1/profile/{uuid}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ARC_ACCESS_TOKEN}' \
--header 'Arc-Site: {siteID}'

Migrate users

Arc XP Identity migration API allows you to seamlessly transfer your current customer profile and login information from your previous identity provider. see Use identity developer APIs to migrate users into Arc XP Identity for additional details.

POST {base_URL}/identity/api/v1/migrate

User Sign Up

When you first start using Arc XP Subscriptions, you’re going to need to sign up, or register, new users in your organization. New users can be created with the following API request.

POST {base_URL}/identity/api/v1/signup

The username and password are sent to Arc XP in the identity attribute of the request payload. Additional user attributes can be set in the profile attribute of the user sign up request payload to save other user information like first name, last name, email, etc.

A successful response to this API will result in a new user being created in Arc XP. The API response body will contain a lot of information about the new user, but the most important piece of data will be the attribute called uuid. Arc XP calls this the clientId. The clientId is the unique identifier of a user in the Arc XP subscriptions application. You can use the clientId to perform additional actions on the user.

View Users

Once you have some users created in your organization, you can search for all users with the following API request.

GET {base_URL}/identity/api/v1/user

The API accepts search parameters for email, first name, last name, and display name, to narrow down the results. Partial matching will be used for all search attributes. The response will contain a paginated listing of all users that matched the search criteria.

Note

Avoid using this API as a user report. This API is not designed to handle large amounts of data. If you need to export data, please use our data extraction framework with user as the type.

View And Update Profile

Now that you have created a few users and found the users with our search APIs above, you can use the following API endpoints to view and update a user’s profile record.

GET {base_URL}/identity/api/v1/profile/{uuid}

With the UUIDs retrieved from the sign-up and view API requests, you can use the PUT and the PATCH APIs to update the user’s profile record. For example, when you need to update a user’s email address or first or last name, you can do it with these APIs:

PUT {base_URL}/identity/api/v1/profile/{uuid}
PATCH {base_URL}/identity/api/v1/profile/{uuid}

The response will contain the updated user’s profile record if the request was successful.

Password Reset

You can use the password reset API to reset the user’s password. The request will take the user’s old and new password and the new password must meet or exceed the password requirements configured for your organization.

If you have a social sign in provider configured, like google or facebook, then there is the possibility that the user does not have a password login set with Arc XP identity. When a user that has only a social sign on profile configured calls this API, then a new password login will be created for this user. We will accept any value in the old password during the password verification processing for the social sign in users.

PUT {base_URL}/identity/api/v1/password/{uuid}

Remove All User Sessions

A user can be logged into their account on many devices. A call to this API will invalidate all the user’s sessions on all devices, and force the user to log into their account to access more content. If needed, this request has the option to reset the user’s password.

PUT {base_URL}/identity/api/v1/:clientId/invalidate/sessions

Anonymize/Delete User

To remove users from Arc XP Identity, the following APIs can use either uuid or email to automatically delete the user account. If the call was sucessfull a ACCOUNT_DELETION_REQUEST_COMPLETED event is dispatched, all the user data will be permanently anonymized and all access will be removed.

If you are using Subscriptions, prior to deletion, you can check for any active subscriptions for the user, user account with active susbscriptions cannot be anonymized. If the account is deleted, all critical financial and tax information is anonymized too.

This is a permanent action and cannot be undone.

DELETE {base_URL}/identity/api/v1/user/anonymize/uuid/{uuid}
DELETE {base_URL}/identity/api/v1/user/anonymize/email/{uuid}

Schedule and download a report

For reports, you will need to call two APIs: the first schedules a report, and the second downloads the report. Reports supports dates with ranges of within 7 days or less and they can be scheduled on json or csv format.

Before generating and downloading reports take a look into the Data extraction framework. We strongly recommend using the data extraction framework instead of the standard reports.

There are different types of reports available.

Report type	Description	Report attributes
sign-up-summary	Registered accounts	CREATED_ON, CLIENT_ID, LEGACY_ID, LAST_SUCCESS, MODIFIED_ON
data-export
account-activity-last-login	Accounts with a last login within the date range	CLIENT_ID, CREATED_ON, MODIFIED_ON, EMAIL, STATUS_ID, LAST_SUCCESS, TYPE_ID
account-activity-last-modified	Accounts with a last modified within the date range	CLIENT_ID, CREATED_ON, MODIFIED_ON, EMAIL, STATUS_ID, LAST_SUCCESS, TYPE_ID

Schedule report

A report can be scheduled by calling.

POST {base_URL}/identity/api/v1/report/schedule

You will need to pass the startDate, endDate, reportType, reportFormat. Also a name needs to be set up, which could be any string.

If the schedule report API call was successful, the API will return some information, as part of this you will found a jobID. This value is needed to call the download report API.

Download report

A report can be downloaded by calling.

GET {base_URL}/identity/api/v1/report/{jobID}/download

Example

curl --location --request POST 'https://{base_URL}/identity/api/v1/report/schedule' \
--header 'Content-Type: application/json' \
--header 'Arc-Site: {siteID}' \
--header 'Authorization: Bearer {ARC_ACCESS_TOKEN}' \
--data '{
"name": "report2",
"startDate": "2024-06-01T01:54:45.000Z",
"endDate": "2024-06-08T02:54:45.000Z",
"reportType": "sign-up-summary",
"reportFormat": "csv"
}'