API keys

A key lets your server call the API for one store. It starts with dmr_live_followed by 32 characters, and every key is live: what you do with it is real work, the same as in the app, and is billed on your store's monthly usage invoice. Create keys in your console under API Keys.

Send the key

Send the key in the Authorization header of every call, never in the URL.

curl https://api.diamra.com/v1/... \
  -H "Authorization: Bearer $DIAMRA_API_KEY"

Who answers for a key

The person who creates a key is its custodian. The console records who created each key and when, and shows both in the keys table. Everything done with a key is billed to your store's monthly usage invoice, and the key's custodian answers for all of it, including calls made by anyone who got hold of the key, until the key is revoked.

When a custodian leaves your team, have someone else create a new key, move your servers to it, and revoke the old one.

Keep keys secret

On your side:

• Keep the key on your server. Never put it in a web page, a mobile app or anything else a customer can download.
• Read it from an environment variable or your host's secret manager. Don't write it into your code.
• Keep it out of version control. Add .env files to .gitignore, and turn on secret scanning if your code host offers it.
• Give each server or service its own key, named after it, so you can revoke one without stopping the others.
• Let as few people as possible see it. Never send it by email, chat or a support ticket. Diamra never asks for your key.
• Replace keys from time to time: create a new key, deploy it, check that calls work, then revoke the old one.

// Read the key from the environment, never from your code.
const DIAMRA_API_KEY = process.env.DIAMRA_API_KEY;

const res = await fetch("https://api.diamra.com/v1/...", {
  headers: { Authorization: `Bearer ${DIAMRA_API_KEY}` },
});

More on keeping secrets: OWASP Secrets Management Cheat Sheet (opens in a new tab) and The Twelve-Factor App: Config (opens in a new tab).