Enabling API Access | Axero Documentation

Before users can create Bearer tokens and access the Axero REST API, an administrator must enable API access and configure appropriate security settings. This guide walks through the complete setup process, from enabling Bearer token support to configuring security levels that match your organization's requirements.

📋 Prerequisites: You must have site administrator privileges to configure REST API settings. These changes affect all users in your organization and should be planned accordingly.

Step 1: Enable Bearer Token Support

Bearer token support is controlled by the Security level setting on the REST API Settings screen, so you do not edit anything by hand to turn it on:

1. Open REST API Settings: Go to Control Panel > System > REST API Settings
2. Choose a security level: Anything above Legacy enables Bearer tokens. Step 2 below describes what each level changes.
   • The selector writes two system properties for you, EnableLegacyAPIKey and EmulateLegacyAPIKey, and reads them back to show which level the site is on. Legacy is both true, High is EnableLegacyAPIKey = false with EmulateLegacyAPIKey = true, and Extra high is both false.

   If you need a legacy API key on a site already using bearer tokens, for example for an older integration that cannot be changed, this is the one case that does need a hand edit. In Control Panel > System > System Properties, set EmulateLegacyAPIKey to false and EnableLegacyAPIKey to true. The legacy API key option reappears in user preferences and the key can be created.

   That combination is a fourth level the Security level selector does not offer, and while the site is on it, the selector is hidden. Put the properties back by hand to return the selector to the screen.

   Do this deliberately and put it back afterwards. While it is reversed, everyone on the site sees the legacy key option again.
3. Save Changes: Apply the configuration to activate Bearer token support

Step 2: Configure Security Level

After enabling Bearer token support, you'll need to choose the appropriate security level for your organization. This decision determines which authentication methods are available and how strictly API access is controlled.

Quick Reference: Which Security Level Should You Choose?

Navigate to REST API Settings and select one of the following security levels. Read each option carefully to understand the features and limitations:

🔁 Legacy Security (Transitional)

Maintains backward compatibility by supporting both legacy API keys and Bearer tokens during the migration period.

The first step of that migration is an inventory, and Axero cannot produce it for you. The platform does not record which authentication method an API call used, so nothing in the product can list the integrations still on a legacy key, and call volume alone cannot separate a legacy integration from ordinary browsing or from mobile app traffic. Build the list from your own side: the systems and scripts your teams have written against the API, and the accounts they run as. A starting point is the set of accounts that hold a legacy API key. Do this before the deadline above rather than after it, because once legacy support ends, an integration you did not know about simply stops.

🔐 High Security (Recommended)

The recommended security level eliminates legacy API keys while keeping existing third-party integrations working. This mode provides enhanced Bearer token management with configurable expiration controls.

⚠️ Migration Required: Before enabling High Security, ensure all applications using legacy API keys are updated to use Bearer tokens. Legacy API keys will immediately stop functioning.

Bearer Token Expiration Configuration

High Security mode provides granular control over token expiration policies:

• Default Expiration: Set a default expiration period that pre-fills when users create new tokens (e.g., 1 year, 6 months)
• Maximum Expiration: Enforce an organizational maximum for token duration to maintain security compliance
• Allow Unexpiring Tokens: Optionally permit tokens without expiration dates for specific use cases (use with caution)

🔒 Extra High Security (Maximum Protection)

The highest security level that provides maximum protection by requiring Bearer tokens for all API access. This mode completely disables username/password authentication, ensuring all API requests use cryptographically signed tokens.

Step 3: Enable User Role Permissions

After configuring security levels, ensure that user roles have the appropriate REST API permissions:

1. Navigate to Role Management: Go to Control Panel > People > Roles
2. Select User Roles: Choose the roles that should have REST API access
3. Enable API Permissions: Grant "REST API Access" permission to selected roles
4. Save Changes: Apply the permission changes

🔑 Permission Note: Users without REST API permissions will not see the Authorizations section in their account settings and cannot create Bearer tokens.

Once Bearer token support is enabled and user permissions are configured, users can create their own Bearer tokens: Creating Bearer Tokens

After Setup

After completing the REST API setup:

1. Test Configuration: Verify that authorized users can access the Authorizations section
2. Create Test Tokens: Have users create test Bearer tokens to validate functionality
3. Update Documentation: Inform your team about the new token creation process
4. Monitor Usage: Track token creation and usage patterns for security compliance

Related pages

• Using the REST API (how to send the token, and what a 401 from the server rather than from Axero looks like)
• Creating Bearer Tokens (where each person creates the token this page lets them create)
• REST API: Permissions (the role permissions Step 3 grants, endpoint by endpoint)