Skip to main content
Proper authentication is essential to secure your Genuka integration. This guide explains how to authenticate your API requests, outlines error scenarios, and presents best practices. We have several ways to authenticate our requests. We can either use the API Key or the token that we must add to the header. In the following, we will present both methods.
⚠️ Important — Verify the HMAC before any authentication Before performing any authentication or token exchange, your application must verify the HMAC signature sent by Genuka in the installation callback. This step ensures the request truly comes from Genuka and prevents malicious third-party access. 👉 Learn how to verify the HMAC →

​
Using API Key authentication

Genuka uses API keys to authenticate requests.
However, API Key authentication is reserved exclusively for Genuka clients who wish to connect their stores or perform actions directly from their own company account. ⚠️ Developers building external applications should not use this method — their integrations are authenticated via Access Tokens instead (see the next section).

​
How it works

  1. You can find these in your Genuka Dashboard → Settings → API Keys.
  2. Generate a new key and copy it.

​
Example request

curl -X GET "https://preprod-api.genuka.com/2023-11/orders" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Company: YOUR_COMPANY_ID" \
  -H "X-Shop: YOUR_SHOP_ID"

​
Authentication with Access Token

Besides API keys, you can authenticate requests using an Access Token.
This method is used for applications installed by a company via the Genuka platform. When a company installs your app, Genuka sends a callback with information such as company_id, code, timestamp, hmac, and redirect_to.

​
How it works

  1. When your application is installed by a company, it receives a callback from Genuka containing company_id, code, timestamp, hmac, and redirect_to.
  2. Your application should use its GENUKA_CLIENT_ID, GENUKA_CLIENT_SECRET, GENUKA_REDIRECT_URI along with the endpoint https://api.genuka.com/oauth/token to exchange the code for an access token.
  3. Store the company as a user in your database.
  4. Keep the access token private to ensure secure API requests on behalf of that company.
  5. Include the token in the Authorization header for all subsequent requests.

​
Example: Using the Access Token


const params = new URLSearchParams({
  grant_type: "authorization_code",
  code: "CODE_FROM_CALLBACK",
  client_id: process.env.GENUKA_CLIENT_ID,
  client_secret: process.env.GENUKA_CLIENT_SECRET,
  redirect_uri: process.env.GENUKA_REDIRECT_URI,
});

const tokenResponse = await fetch("https://api.genuka.com/oauth/2023-11/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: params,
});

const { access_token } = await tokenResponse.json();

// Use access_token to get orders
const ordersResponse = await fetch("https://api.genuka.com/orders", {
  headers: { Authorization: `Bearer ${access_token}` },
});

const orders = await ordersResponse.json();
console.log(orders);

​
Common Authentication Errors

If authentication fails, Genuka returns clear error messages:
Error ScenarioHTTP CodeMessageLikely Cause
Missing API Key401"code": 401, "message": "API key is missing"Authorization header not provided
Invalid or Revoked Key401"code": 401, "message": "Invalid API key"Wrong or expired API key
Unauthorized Live Access403"code": 403, "message": "Sandbox key not allowed for live operation"Using sandbox key for production request