Authentication and API keys

DEUNA credentials answer two different questions: which merchant application is calling, and, when applicable, which signed-in customer is using it. Start with where the request runs and whose authority it needs, then confirm the exact requirement in the endpoint catalog.

Decide which credential to useAsk Athia about this#

Ask these questions in order:

1. Does the request run in a browser or mobile application? Use the public API key or application context documented for the SDK or endpoint. Never place the private key in that client.
2. Does your backend perform a merchant operation? Use the private API key in X-Api-Key for server-to-server calls such as creating, retrieving, capturing, refunding, or voiding an order.
3. Must DEUNA recognize the signed-in customer? Add the customer's short-lived access token as Authorization: Bearer … only when the endpoint supports it. This is what gives the request customer-specific context for resources such as profile data, addresses, stored payment instruments, or customer-authorized wallet flows.

Choose the correct credentialAsk Athia about this#

Public API key: client-side integrationAsk Athia about this#

Use the public API key when DEUNA code runs in an untrusted client, such as a browser or mobile application. Typical uses include initializing a DEUNA widget or SDK and identifying the merchant and environment for supported client-side tokenization and payment experiences.

A public key is intentionally safe to include in client configuration, but it is not a secret substitute and it does not grant permission to perform captures, refunds, voids, or other merchant-backend operations. Keep the public key paired with the correct sandbox or production environment.

Private API key: server-to-server authorizationAsk Athia about this#

Use the private API key when your trusted backend calls a merchant endpoint. Merchant operations that use API-key authorization expect the private key in X-Api-Key, never in Authorization: Bearer ….

curl --request GET \
  --url https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN \
  --header "X-Api-Key: YOUR_PRIVATE_API_KEY"

const response = await fetch("https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN", {
  method: "GET",
  headers: {
    "X-Api-Key": "YOUR_PRIVATE_API_KEY"
  }
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "GET",
    "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN",
    headers={
        "X-Api-Key": "YOUR_PRIVATE_API_KEY"
    },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: YOUR_PRIVATE_API_KEY"
  ]
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN"))
      .header("X-Api-Key", "YOUR_PRIVATE_API_KEY")
      .method("GET", HttpRequest.BodyPublishers.noBody())
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  request, err := http.NewRequest("GET", "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN", nil)
  if err != nil { panic(err) }
  request.Header.Set("X-Api-Key", "YOUR_PRIVATE_API_KEY")

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Customer Bearer token: signed-in user contextAsk Athia about this#

Use a customer access token when the operation must act in the context of a signed-in DEUNA customer and the endpoint documents Bearer support. Send it in the Authorization header:

Authorization: Bearer USER_ACCESS_TOKEN

The Bearer token answers which customer is acting. The API key answers which merchant application or backend is calling. Depending on the endpoint, a customer request can therefore require both an application API key and the customer's Bearer token.

Do not send a Bearer token for a guest flow merely because the header is available. Do not use a merchant private key as a Bearer token, and do not treat a customer token as authority for merchant-only operations. If your backend forwards customer context, forward it only to an endpoint that explicitly supports the combination.

EnvironmentsAsk Athia about this#

Sandbox and production are isolated. Each environment has its own base URL, API keys, merchant configuration, connections, data, and payment state.

Store and rotate keysAsk Athia about this#

• Store private keys in a secrets manager or protected runtime configuration.
• Scope access to the service and environment that need the key.
• Redact credentials from request logs and support attachments.
• Deploy a replacement key before revoking the old key so production traffic continues safely.
• Coordinate key issuance and rotation with your authorized Admin operator or DEUNA TAM.

Authentication failuresAsk Athia about this#

An authorization failure normally returns 401 Unauthorized or 403 Forbidden. Before retrying, verify:

1. The credential is present in the documented header.
2. The key belongs to the requested environment and merchant.
3. The endpoint supports the authorization method you sent.
4. The key or customer token has not expired or been revoked.
5. Any required merchant, store, or customer context is present.

Do not retry an authorization error indefinitely. Preserve the response request_id when available and include it when contacting support.

Rate limitsAsk Athia about this#

DEUNA does not apply one public requests-per-second value to every integration. The API Gateway evaluates configured limits as a maximum number of requests within a time window. The effective limit can vary by merchant, environment, HTTP method, and endpoint.

When a request exceeds an applicable limit, the gateway returns 429 Too Many Requests with a Retry-After header. A route-level response has this shape:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1

{
  "error": "rate_limit_exceeded",
  "message": "maximum requests",
  "code": 429,
  "endpoint": "/merchants/orders",
  "total_requests": 101,
  "retry_after": "1s"
}

Response fields can differ when a gateway-wide safeguard rejects the request. Treat the HTTP status and Retry-After header as authoritative.

Handle 429 responses safely

1. Stop sending requests for at least the number of seconds in Retry-After.
2. Retry with exponential backoff and jitter instead of immediately releasing queued traffic as another burst.
3. For the same payment operation, reuse the original idempotency key and the exact same request body.
4. Coordinate throttling across workers and application instances; per-process retry loops can collectively exceed a shared merchant or endpoint limit.
5. If 429 responses continue after traffic is reduced, preserve the response body and request ID, then contact DEUNA Support or your Technical Account Manager (TAM).

Request a limit increase

Ask DEUNA Support or your TAM to review the limit before a planned traffic increase. Include:

• The environment and merchant ID.
• The affected HTTP methods and endpoints.
• Expected sustained and peak request rates, burst duration, and planned rollout date.
• The outbound (egress) public IP addresses or CIDRs used by the merchant systems that call DEUNA.

Do not include API keys, Bearer tokens, or other secrets in a support request.

ContinueAsk Athia about this#