Authentication

The Droplinked API exposes four access tiers. Pick the one that matches what you’re building.

Tier	Credential	Sent as
Public	none	—
Shop API key	per-shop key, issued by the merchant	`x-droplinked-api-key: <key>`
Merchant / customer JWT	login token	`Authorization: Bearer <jwt>`
Integration key	partner key for Integration Services	`integration-api-key: <key>`

The live OpenAPI spec declares the first two machine-readable schemes:

"securitySchemes": {
  "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" },
  "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-droplinked-api-key" }
}

Public endpoints (no auth)

Public read paths are open and unauthenticated — built for storefronts, catalogs, and AI agents that read a merchant’s published inventory.

curl https://apiv3.droplinked.com/shops/v2/public/name/example-shop
curl "https://apiv3.droplinked.com/product-v2/public/shop/example-shop?page=1&limit=24"
curl https://apiv3.droplinked.com/checkout/example-shop/payment-intent-resolver

Shop API key

A shop API key is the credential for server-to-server integrations scoped to one merchant’s shop. It is the scheme used across the partner-facing surfaces in these docs. Send it in the x-droplinked-api-key header:

curl https://apiv3.droplinked.com/some/keyed/endpoint \
  -H "x-droplinked-api-key: dl_live_EXAMPLE_KEY_DO_NOT_USE"

Two fallbacks are accepted for gateway compatibility and are checked in this order:

x-droplinked-api-key header (preferred)
x-gravitee-api-key header
?api_key= query parameter — avoid this: query strings land in access logs and browser history. Use a header.

Key lifecycle

Keys are created and managed by the merchant on their own shop, under a merchant JWT:

Operation	Endpoint
Create a key	`POST /shops/v2/api-key`
List keys	`GET /shops/v2/api-key`
Read one key	`GET /shops/v2/api-key/:id`
Update a key	`PATCH /shops/v2/api-key/:id`
Rotate (regenerate)	`POST /shops/v2/api-key/:id/regenerate`
Revoke	`POST /shops/v2/api-key/:id/revoke`

Keys are stored as a SHA-256 hash — the plaintext is returned once, at creation, and cannot be recovered afterwards. Keys may carry an expiry; an expired key is marked EXPIRED on first use and rejected from then on. Rotate by calling regenerate, deploying the new value, then confirming the old one is no longer in use.

Merchant / customer JWT (Bearer)

Authenticated actions (managing a shop, products, carts, orders) use a Bearer JWT.

# 1. Obtain a token
curl -X POST https://apiv3.droplinked.com/merchant/login \
  -H "Content-Type: application/json" \
  -d '{"email":"merchant@example.com","password":"<password>"}'
# → { "statusCode": 200, "message": null, "data": { "accessToken": "<JWT>", ... } }

# 2. Call an authenticated endpoint
curl https://apiv3.droplinked.com/shops/v2 \
  -H "Authorization: Bearer <JWT>"

Auth routes are aggressively throttled — plan your integration tests around it. POST /merchant/login allows 5 attempts per 15 minutes, enforced both per-IP and per-email, so rotating source IPs does not widen the window. The sixth attempt returns 429 regardless of whether the credentials are correct. Full table on Rate limits.

Integration key (server-to-server)

Partner/integration services authenticate to the Integration Services layer with an integration-api-key header. This is for backend-to-backend calls, not browser or agent clients.

curl https://service.droplinked.com/locations/countries \
  -H "integration-api-key: <integration key>"

This key also gates the PSP callback ingress (POST /payment/webhook/generic). Treat it as a payment credential: it is one of the two factors that can move an order to paid. See Webhooks.

Handling credentials

Never ship a key in front-end code, a mobile bundle, or a public repository.
Use one key per integration so you can revoke a single consumer without an outage.
Rotate on staff changes and on any suspected exposure — regenerate is online and does not require support.
Droplinked never asks for your key over email or chat.

Next: environments

Base URLs for production and development.

Get Started

Core Concepts

Deploy & Operate

Trust Fabric Guides

Order Lifecycle

Payments

Payment Integrations

Fulfillment Integrations

Library

Platform & Architecture

Public endpoints (no auth)

Shop API key

Key lifecycle

Merchant / customer JWT (Bearer)

Integration key (server-to-server)

Handling credentials

Next: environments

​Public endpoints (no auth)

​Shop API key

​Key lifecycle

​Merchant / customer JWT (Bearer)

​Integration key (server-to-server)

​Handling credentials

Next: environments

Public endpoints (no auth)

Shop API key

Key lifecycle

Merchant / customer JWT (Bearer)

Integration key (server-to-server)

Handling credentials