LogoZebo Studio

Authentication

Commerce authenticates API requests with an opaque bearer key. Keep the key in server-side secret storage and include it in the Authorization header for every request.

Prerequisites

  • A Commerce application
  • An API key generated from the dashboard
  • A server-side runtime that can read secrets from its environment

Send the bearer header

Set the header value to Bearer followed by the complete opaque key:

Authorization: Bearer <SECRET_KEY_TOKEN>

Do not parse the token, infer an environment from its characters, embed it in browser or mobile code, commit it to source control, or log it. A missing, malformed, or invalid credential returns 401 Unauthorized.

Make an authenticated request

This example creates a finalized order through the public POST /orders/new endpoint using native HTTPS. The API returns { "order": { ... } }; unwrap order before reading its hosted invoice URL.

Authenticated request

POST
/orders/new
response=$(curl https://api.zebo.dev/orders/new \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: auth-example-order-123" \
  -d '{
    "finalize": true,
    "line_items": [{
      "product": {
        "name": "Premium Subscription",
        "price": { "currency": "ghs", "value": 5000 },
        "quantity": 1
      },
      "type": "product"
    }]
  }')

invoice_url=$(jq -er '.order.invoice.format.web.url' <<< "$response")

Store credentials safely

Read the key from environment configuration or a secret manager:

COMMERCE_API_KEY=<SECRET_KEY_TOKEN>

Restrict access to the deployment identities that make Commerce requests. If a key may have been disclosed, generate a replacement, deploy it, verify requests with the new credential, and retire the old key through the supported product surface.

Handle authentication failures

A 401 Unauthorized response means Commerce could not authenticate the request. Verify that the header uses the exact Bearer <token> format, the complete token was loaded, and the credential is still active. Do not print the key while diagnosing the failure.

Authentication proves which application made the request. It does not by itself prove a customer's identity or authorize a payment; keep those decisions in the corresponding checkout or verification flow.

Was this page helpful?