Introducing a major update to API tokens that gives your engineering and admin teams precise, "least-privilege" control over API access.

The Challenge: The "All-or-Nothing" API Key

Previously, API tokens (now referred to as Legacy tokens) were company-wide, granting full read and write access to all Constructor endpoints across all your indexes. While powerful, this created potential risks. A leaked token technically, could expose all your data, and a simple misconfiguration in a script could accidentally apply changes to the wrong environment.

The Solution: API tokens with Custom Level of Access

Now, you can build API tokens with a specific, limited scope. When creating a new token, you can define:

• Indexes: Specify which indexes the token can access. This is perfect for isolating your Production, Staging, and Dev environments or managing different websites.
• Scopes: Select which API endpoints the token can use (e.g., searchandising.refined_queries, searchabilities,  synonyms).
• Permission: Define the permission level for those scopes: Read & Write, Read, or Write.
• Expiration Date: Set an optional expiration date. We recommend renewing API tokens regularly.

By limiting access to what is really needed, you reduce security risks if a token gets compromised and rule out the possibility of applying changes to the wrong environment.

Putting API Tokens into Practice

This new control allows you to securely manage complex, multi-team workflows:

• For Integration Scripts: Create an API token that has access only to scopes within the dev_index to test things before applying changes in production.
• For Regional Teams: Give your EU engineering team an API token that can Read & Write to all scopes only on the eu_site index, preventing accidental changes to the US site.

Better Together: API Tokens + Customizable User Roles

This update works hand-in-hand with our recent Customizable User Roles feature. Only users assigned with a role that has Manage API tokens permissions can set up API tokens. Users' ability to create API tokens is limited by their role permissions. An administrator can create tokens for any scope, but a user with a specific role (e.g., "US Merchandiser") can only create API tokens for the indexes and features they are already permitted to access. 

This ensures your permission model is consistent, from the dashboard UI right down to the API.

A Note on Legacy API Tokens

Your existing tokens (now labeled Legacy tokens in the dashboard) will continue to work without interruption. However, you can no longer create new tokens of this type. We highly recommend you audit your existing integrations and begin migrating to the new, more secure API tokens as part of your team's security best practices.

How to Get Started

This feature is now live for all customers. Administrators and users with the appropriate permissions can create new tokens by navigating to Integration > API Tokens in the dashboard.

For a complete, step-by-step guide, please visit our updated documentation: Generate and manage API tokens.

If you have any questions or feedback on the new feature or the Constructor dashboard in general, please connect with your Customer Success Manager or contact us through support@constructor.io.