Authentication

How to authenticate API requests with store API keys, how permissions work and how to keep keys safe.

The Wafle API authenticates every request with an API key. Each key belongs to one store account and carries only the permissions you gave it.

Send your key

Send the key in the X-Wafle-Store-Key header:

curl "https://wafle.click/api/v1/stores/your-store/orders" \
  -H "X-Wafle-Store-Key: $WAFLE_KEY"

Use HTTPS for every request. Requests over plain HTTP are not supported, and you should never send a key over an unencrypted connection.

Create, rotate and revoke keys

Manage keys from your account settings under API keys:

  • Create a key for each integration, with a descriptive name.
  • Rotate a key to replace it with a new one, for example on a schedule or when a teammate leaves. Update your integration with the new key, then retire the old one.
  • Revoke a key to stop it working immediately.

A key is shown only once when it is created. If you lose it, rotate it to get a new one.

Permissions

A key can be limited to the permissions it needs, written as a resource and an access level, such as orders:read or products:write. A request that needs a permission the key does not have fails with HTTP 403. Give each key the smallest set of permissions that works, so that a leaked key can do less harm.

Keep keys safe

  • Store keys in environment variables or a secrets manager. Never commit them to a repository.
  • Never put a key in code that runs in a browser or a mobile app. Call the API from your server instead.
  • Use a separate key for each integration so that you can revoke one without affecting others.
  • Revoke any key you think has been exposed, then create a replacement.

Authentication errors

| Status | Meaning | | --- | --- | | 401 | The key is missing, malformed or revoked. | | 403 | The key is valid but does not have permission for this request or this store. |

See Errors and rate limits for the error format.

Connecting an AI assistant

Assistants do not use keys that you paste into code. They connect through the AI assistant (MCP) integration and sign in on your behalf. See Connect an assistant.

Was this helpful?

Need help with an integration? Contact support.