Using Developer Access Tokens to Access the Arc XP APIs

Arc XP applications include a robust API layer to create and manage data. Arc XP APIs can be used for:

• Building your own tools on top of the Arc XP platform.
• Building custom integrations with external software.
• Generating reports.
• Migrating data.

Most Arc XP API endpoints are accessible over HTTPS and require authentication. This guide demonstrates how to fetch basic data from Arc XP using the curl tool in the command line.

warning

Do not distribute or embed access tokens in client-side applications (including native iOS or Android) because they are permissive and are not user-scoped. Do not commit access tokens to code repositories.

Prerequisites

To start working with Arc XP APIs, ensure you have:

• Access to the Developer Center app in your Arc XP instance
• Understanding of REST APIs
• Familiarity with HTTP headers and authentication methods

Step 1. Generate an access token

Take the following steps to generate an access token in the Developer Center:

1. Access your Arc XP instance at:

   https://{org-id}.arcpublishing.com

2. Enter your Okta credentials. The Arc XP dashboard displays.

3. Click the developer center tile under the Administration section.

   

   The Access Tokens page displays.

4. Click the New access token button.

   A modal window displays.

5. Select the Read only access token type.

6. Click the Create token button.

   The token description page displays.

7. In the text field, write a description for your token.

8. Click the Generate token button.

   The generated access token page displays.

9. Copy your access token to a safe place.

Important

The generated access token page is the only opportunity you have to copy your token. If you fail to do so, you must create another token. Revoke unused tokens from the Access Tokens page for enhanced security.

Step 2. Determine your organization’s API domain

Each Arc XP user exists within an organization, and might be your employer’s name. Each organization is assigned a unique domain to access the Arc XP APIs.

To obtain your API Domain, add api. to the beginning of the domain you use to access your Arc XP website. For example:

https://api.{org-id}.arcpublishing.com

Tip

You can specify a non-production environment by adding it after api.. For example:

https://api.sandbox.{org-id}.arcpublishing.com

The default non-production environments in Arc XP are: sandbox, development, and staging.

Step 3. Access the Arc XP APIs

To access RESTful endpoints in the Arc XP APIs, include your access token in an HTTP Authorization header using the Bearer Authentication Scheme.

For example, you can use the Site Service API to get a list of websites you have created in your organization. Paste the following to your command line:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X GET https://api.{org-id}.arcpublishing.com/site/v3/website/

Note

Ensure to replace ACCESS_TOKEN with your actual token.

Types of access tokens

Because access tokens bypass the user-level permissions structure of Arc XP, there are different token types for different purposes. In general, you must use:

• A Read-only token if you do not need to modify content within Arc XP.
• A Restricted-access token for specific and secure access to the fewest Arc XP applications necessary.
• An All-access token only for more advanced use cases.

Although some token types are non-destructive, all tokens can access data generated by Arc XP applications. This includes internal notes, unpublished content, and sensitive user data. Any person with an access token must be considered to have all permissions. You must not use access tokens as a replacement for standard user login and authentication mechanisms.

Table 1 lists the available token types and their purposes.

Token type	Purpose
Read-only	Enables you to retrieve data without modifying it.
Restricted-access	Grants limited permissions to specific applications.
All-access	Provides full read and write access to all API endpoints.
PageBuilder	Enables deployment of bundles to the Arc XP platform.

Table 1. Access token types

The following sections detail each type of access token:

• Read-only tokens
• Restricted-access tokens
• All-access tokens
• PageBuilder access tokens

Read-only tokens

Arc XP recommends read-only access tokens for the most common use cases, such as retrieving data from the Content API.

A read-only token grants a user or application non-destructive access to the Arc XP APIs. Read-only tokens can access but not modify data generated by any user in your organization.

The following table shows the types of requests allowed and forbidden in Arc XP APIs with a read-only access token:

	GET	HEAD	OPTIONS	POST	PUT	PATCH	DELETE
Content API	✅	✅	✅	❌*	❌	❌	❌
Draft API	✅	✅	✅	❌	❌	❌	❌
Site API	✅	✅	✅	❌	❌	❌	❌
Author API	✅	✅	✅	❌	❌	❌	❌
Tags API	✅	✅	✅	❌	❌	❌	❌
Photo Center API	✅	✅	✅	❌	❌	❌	❌
Global Settings API	✅	✅	✅	❌	❌	❌	❌

Note

* Read-only access tokens can perform POST requests to the URLs endpoint of the Content API.

Restricted-access tokens

Restricted-access tokens work with specific Arc XP applications. Restricted-access tokens enable greater control to improve your organization’s security. When granting access to APIs, you can grant read access to one application while permitting read or write access to another application.

Limiting the scope of your access tokens strengthens your organization’s security and ensures compliance with security standards, particularly with protected data that cannot be exposed to third-party integrations.

Note

You cannot adjust the scope of a restricted-access token after it is created. If you need to define a different scope, you must create and include a new token it in your integration.

All-access tokens

Arc XP recommends All-access tokens for trusted machine-to-machine integrations. Applications that generate, ingest, or modify content into Arc XP without human intervention must use all-access tokens.

All-access tokens grant a user or application full access to Arc XP APIs. Requests of any type are allowed in any endpoint of the Arc XP APIs.

Users provision and revoke All-access tokens using the Developer Center. Users must have the “Create Admin Access Tokens” privilege to provision.

PageBuilder access tokens

PageBuilder Engine generates PageBuilder access tokens when deploying a bundle. In most cases, PageBuilder access tokens are completely opaque to users.

PageBuilder access tokens have the same access privileges as read-only tokens, and support the same API requests.

PageBuilder Engine automatically provisions and revokes PageBuilder access tokens as necessary for deployments to proceed. Users cannot manually provision or revoke PageBuilder access tokens in the Developer Center.

For more information on PageBuilder access tokens, see How Access Tokens Work In PageBuilder .

Limitations on access tokens

The following limitations apply to Arc XP access tokens:

• A single organization can have a maximum of 300 access tokens.

• A single user can have a maximum of 30 access tokens.

important

When using Arc XP access tokens, remember:

• Access tokens do not expire.

• Any user can revoke their own access tokens. Administrators with the appropriate permissions can also revoke access tokens created by any user.

• Tokens are not automatically revoked when their corresponding account is removed from Okta or another integrated login system. Administrators are responsible for revoking access tokens when users leave an organization.

Access token best practices

Access tokens have a wide scope and should be handled with care. To maximize their effectiveness, consider the following:

• Do not generate tokens on behalf of other users. You can grant access privileges by assigning users and privileges to the correct squad and role in the Permissions tile of the Arc XP dashboard. In this way, users can create and revoke their own tokens. This removes the need to transmit tokens in an insecure way from one user to another and protects you from being responsible for tokens that you are not using.

• Rotate tokens regularly. Access tokens are easy to create and revoke, and you can maintain multiple access tokens simultaneously. You can “rotate” an old access token by creating a new token, deploying your application with the new token, and then revoking the old token after your application is in production. Doing this regularly minimizes the amount of time that a compromised token can be exploited.

• Generate a unique token for each application. If a token is compromised, you may find it easier to revoke a token that affects the narrowest slice of functionality possible. Having a unique token for each distinct application or use case means that you only need to replace one token later on and can revoke compromised tokens more quickly.

• Do not use access tokens in client-side applications. Access tokens are a secure solution only for your trusted backend applications to send and retrieve data directly to Arc.

• Encrypt and secure tokens that are embedded in applications. You must not store tokens in plaintext.

• Use the smallest-scoped token possible. Don’t use an all-access token when a restricted-access or read-only token works.

• Do not send or share tokens. Access tokens must not be shared through unencrypted communication channels.