API Keys

API Keys are machine credentials for calling the Makaira API with HMAC. In the admin UI they appear as API Keys. Older docs and shop modules call the same credential a Shared Secret.

They are not user passwords and not the External Apps clientSecret.

You need the API Keys permission (secret.read / secret.write). On the default roles that is the Owner role. Open Administration → API Keys on the dashboard.

Create a key

1. Create an API key and set a title (required). You can add a description, an expiry date, and whether the key is active.
2. Grant API permissions. Read covers GET requests; write covers POST, PUT, and DELETE. You can only assign permissions you hold yourself.
3. Optionally apply a preset so you do not pick endpoints one by one:
   • Importer — shop Connect / import
   • Search — search API
   • Shopify — Shopify integration
4. Save and copy the plaintext key immediately. Makaira stores it encrypted and only shows the full value again if your user has every permission on that key. The list view otherwise shows a masked value such as a***x.

Inactive or expired keys cannot authenticate.

Keys migrated from the original single Shared Secret have the description legacy secret. That key still works for shop Connect. You can create a new key with the Importer preset (or equivalent permissions) and paste it into the shop module instead.

Use a key (HMAC)

Send X-Makaira-Nonce and X-Makaira-Hash on the request. The hash is HMAC-SHA256(nonce + ':' + requestBody, apiKey) using a random nonce. Details and examples: Authentication.

Shop Connect

In OXID, Shopware, and other Connect modules the field Secret / makairaSharedSecret is an API key. Use the legacy key or any new key that includes the Connect/importer permissions.

Related APIs

Create, list, update, and delete keys via the Secrets API (/secret). Presets are listed at /secret-preset.