Skip to main content

API Keys

Webround allows you to create API Keys with granular permissions to authenticate external systems — applications, scripts, integrations — without exposing your account credentials.

How they work​

An API Key is used as a replacement for the standard JWT Bearer Token. Any request to the Webround APIs that would normally require an authentication token can be authenticated by passing your API Key in the same header:

Authorization: Bearer API_KEY

Anyone in possession of an API Key has exactly the permissions of that key — no more, no less. This means the key is as powerful as the permissions you assigned to it, and equally dangerous if it falls into the wrong hands.

Storage and security​

Not retrievable

Webround shows your API Key only once, at the time of creation. It is never shown again. If you lose it, you must invalidate it and create a new one.

Some fundamental rules:

  • Never expose it in the frontend. JavaScript code running in the browser is readable by anyone — inspectors, extensions, injected scripts. An API Key in the frontend is a compromised API Key.
  • Always use a secret manager. Your service's secrets, a dedicated vault (HashiCorp Vault, Google Cloud Secret Manager, AWS Secrets Manager, Cloudflare Secrets) are the right place. Never in a committed .env file, never in a hardcoded variable in the code.
  • Do not use it for client-side calls. If you need to call Webround APIs from the browser, build an intermediate endpoint on your server that makes the call — the server knows the key, the browser does not.

Principle of Least Privilege​

Every API Key should have only and exclusively the permissions necessary for its purpose.

  • One integration, one key. Do not reuse the same key for different systems. If one of them is compromised, you can invalidate only that key without impacting the others.
  • Limit permissions to the minimum. An app that reads orders does not need to be able to create products or modify customers. Grant only what is strictly necessary.
  • Invalidate and regenerate immediately if you have the slightest doubt that a key has been exposed — in a log, in an HTTP response, in a Git repository, anywhere.

When to use an API Key​

API Keys are designed for server-to-server communication:

  • An external application that reads orders to manage shipments
  • A synchronization script with an ERP or warehouse
  • A reporting system that exports data to a data warehouse
  • An App Extension that communicates with Webround on behalf of the merchant

They are not designed for the frontend, for mobile applications you do not control, or for any context where the code — and therefore the key — could be inspected by an external user.

Next Steps: Consult the Apps guide to see a concrete example of how to combine API Keys and signed authentication to integrate an external system into your Webround admin panel.