Add API keys

Overview

The backend SDK uses API keys to authenticate requests to the SuperTokens core.

By default, there is no API key required. If you add an API key to the core's configuration or use the managed service, you need to add it to your backend SDK code. Otherwise, the core throws a 401 error.

caution

Running without an API key is only safe when the Core is on a private network reachable exclusively by your backend. If the Core can be reached from anywhere else, configure an API key — and ideally also restrict access by IP address and serve traffic over TLS/SSL. Any caller that can reach the Core can perform administrative operations on your users' data. See Secure the core.

Before you start

This page is only relevant if you are self hosting SuperTokens.

Steps

1. Add the key to the core instance

You can set the API by updating the instance parameters.

 docker run \
    -p 3567:3567 \
    -e API_KEYS=<TO_DO> \ 
    -d supertokens/supertokens-<db_name>

• The format of the value is key1,key2,key3.
• Keys can only contain =, - and alpha-numeric (including capital) chars.
• Each key must have a minimum length of 20 chars
• An example value is "Akjnv3iunvsoi8=-sackjij3ncisds,asnj9=asdcda-OI982JIUN=-a". Notice the , in the string which separates the two keys "Akjnv3iunvsoi8=-sackjij3ncisds" and "asnj9=asdcda-OI982JIUN=-a". In the backend SDK, you should only provide one of these keys.

info

The reason for having multiple API keys is that it allows for key rotation to occur gradually if you have multiple backend systems querying the core.

2. Add the key to your backend code

Update the backend SDK initialization code to include the API key.

import supertokens from "supertokens-node";

supertokens.init({
    supertokens: {
        connectionURI: "<CONNECTION_URI>",
        apiKey: "<API_KEY>"
   },
   appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
   recipeList: []
});