Authentication

To use the Backend API, your API client will have to authenticate itself to the API.

Authentication is handled by a combination of instance key and access token. These have to be provided with every request to the Backend API.

Create an access token

If you already have an access token, go to Example to learn how to use the token.

Access tokens are managed in the app. To create a new access token, go to the Security → Access Token module and click the button that allows you to create a new access token.

🚧

Module missing?

If you don't have access to the security module, please contact support. We manually enable the module on an instance-to-instance basis.

You'll be prompted to fill in a name for your access token. You should strive to have this name be representative of how or by what the access token will be used. For example, you might want to use the name "product sync" if you're going to use the token for synchronizing products with Tweakwise.

Having decided on a name, proceed to create the token.

💡

Token names cannot be changed later, so choose carefully.

Best practices

  • Be descriptive: use names that reflect the purpose of the token. Example: order-sync-service, reporting-dashboard
  • Indicate scope or team if the token is tied to a specific department or job. Example: marketing-analytics, inventory-cronjob
  • Plan for rotation by including a version or date if you expect to replace tokens regularly. Example: frontend-app-2025-01

Things to avoid

  • Generic names like test, token1 → these become confusing later.
  • Personal names like johns-token → tokens should be tied to systems, not individuals.
  • Sensitive data → never include passwords, secrets, or personal information in a token name.

In the next screen you'll see the access token that will have been generated for you. Copy it somewhere and keep it safe!

🚧

For security reasons, we cannot restore a key for you if you lose it. The only option is to delete the old token and create a new one.

Example

To make a request to the Backend API, you'll need to provide both an instance key and an access token. Both of these values must be provided in the headers:

  • TWN-InstanceKey: the instance key
  • TWN-Authentication: the created access token

Note: you can find your instancekey on your Tweakwise App Dashboard

Example, using cURL:

curl --request GET \
     --url https://navigator-api.tweakwise.com/stats/totalproducts \
     --header 'TWN-InstanceKey: YourInstanceKeyHere' \
     --header 'TWN-Authentication: YourAccessTokenHere'