Skip to content
Last updated on June 7, 2023
4 min read

Using Edge Config

Learn how to use Edge Configs in your projects.

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.

Your Edge Config's endpoint is distinct from a Vercel REST API endpoint. Its root is:

https://edge-config.vercel.com

Making requests to an Edge Config endpoint allows you to take advantage of the optimizations that make Vercel's Edge Config reads hundreds of milliseconds faster than alternative options at the edge. These optimizations will not be applied if you request Edge Config data through Vercel REST API.

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.

Alternatively, you can add the Read Access token as a query param appended to the end of the request URL with ?token=<token> as shown in the following example:

https://edge-config.vercel.com/<edgeConfigId>?token=<token>

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:
Your Edge Config ID in the Vercel Dashboard.
Your Edge Config ID in the Vercel Dashboard.
Your Edge Config ID in the Vercel Dashboard.
  • 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

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

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. You can follow our docs on the subject to create one now.

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
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" }'
 
Note: Append the teamId query parameter to if the config is scoped to a Vercel team.

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:

response
{ "token": "your_edge_config_read_access_token_here" }

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

You can find it in the EDGE_CONFIG environment variable generated for your project when you create an Edge Config for it or when you connect an existing one.

Note: A connection string is not created when you create an Edge Config at the account level, until you connect a project.

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.