Using Edge Config

Edge Config is a global data store that offers ultra-low latency read speeds from anywhere in the world thanks to Vercel's Edge Network.

We recommend using the Edge Config client SDK to read data from your Edge Configs. To write data to your Edge Configs, use Vercel REST API as outlined in our docs on managing Edge Configs with the API.

This page outlines all the ways you can interact with your Edge Configs, and our recommended best approaches.

There are multiple ways to read data from your Edge Configs, but we recommend using our Edge Config client SDK in your projects.

If you prefer making direct API requests to your Edge Config, we recommend sending them to your Edge Config endpoint. You can request data through Vercel REST API, but we recommend against ever doing so. Requests to Vercel REST API do not benefit from the optimizations Vercel applies to Edge Config reads. Requests to an Edge Config endpoint do.

Edge Config is available at two separate REST APIs which are built for distinct use cases:

• api.vercel.com: Vercel REST API built for managing Edge Config
• edge-config.vercel.com: Edge Config endpoint intended for reading Edge Config at high volume

• This endpoint is part of the Vercel REST API
• It is intended to manage Edge Configs
• You can use this endpoint to create, update, and delete Edge Configs
• This endpoint is served from a single region and we do not apply any of our read optimizations
• This endpoint is rate limited to 20 Edge Config Item reads per minute
• Reading Edge Config from this endpoint will always return the latest version of an Edge Config
• This endpoint uses the Vercel REST API authentication

• This is a highly optimized, globally distributed, actively replicated endpoint built for global, low latency, high volume reads
• This endpoint has no rate limits
• This is the endpoint @vercel/edge-config reads from
• This endpoint uses the Edge Config's own Read Access tokens

You can use the following routes when querying your Edge Config endpoint:

• /<edgeConfigId>/items
• /<edgeConfigId>/item/<itemKey>
• /<edgeConfigId>/digest

You can authenticate with a Read Access token, which you can add to the Authorization header of your request, setting Bearer <token> as the value.

You can find your Edge Config ID with one of the following methods:

• In your dashboard, under the Edge Config tab. Select your Edge Config, and you'll see the ID under the Edge Config ID label near the top of the page, as shown in the screenshot below:

• Send a GET request to the /edge-config endpoint of Vercel REST API, as outlined in our API reference. The response will be a list of Edge Configs associated with your account (or team, if you add the teamId query parameter)

https://api.vercel.com/v1/edge-config?teamId=<teamId>

A read access token is automatically generated when you connect an Edge Config to a project.

There are multiple ways to create a Read Access token for your Edge Config manually:

• In the Edge Config tab of your project dashboard. See our Edge Config dashboard docs to learn how
• Through a POST request to Vercel REST API

First, you'll need an access token for Vercel REST API, which you must add to an Authorization header with the Bearer <token> pattern to validate requests. To learn more, see Creating an access token.

Then you can send a POST request to the /edge-config/<edgeConfigId>/token path, as shown below, inserting your Edge Config's ID where appropriate:

curl -X 'POST' 'https://api.vercel.com/v1/edge-config/my_edge_config_id/token' \
     -H 'Authorization: Bearer your_vercel_api_token_here' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{ "label": "my edge config token label" }'
 

The response from the API will be a JSON object with a "token" key that contains the value for the Edge Config read access token:

{ "token": "your_edge_config_read_access_token_here" }

A connection string is a URL that connects a project to an Edge Config.

To find and copy the connection string:

1. Navigate to the Tokens tab of your project's Storage dashboard
2. Select the three dots icon displayed in the list of tokens
3. Select Copy Connection String from the dropdown menu

Vercel will optimize your reads to be faster if you set the connection string as an environment variable. Hard-coding your connection string into your application as a string will not allow Vercel to detect the URL and optimize your reads.

The variable can be called anything, but our Edge Config client SDK will search for process.env.EDGE_CONFIG by default. See our environment variables docs to learn how to create one.

Edge Config is optimized for many reads and few writes. To write data to your Edge Configs, see our docs on doing so with Vercel REST API.

Edge Config backups are a backup and restore functionality that allows you to access and roll back to a previous point in time.

Restoring a backup will immediately update the live data, and the data that was live before the restore will become available as a new backup.

Backups are taken when you make any changes either through the dashboard or API. They do not contribute to your storage size. The length of time each backup is held for depends on your plan, see Limits and Pricing for more information.