API Keys Management#

Manage merchant API keys for authentication.

All endpoints require Authorization: Bearer <JWT>. Tenant admins can manage keys for any merchant in the tenant; merchant users can only manage keys of their own merchant and its locations (keys outside that scope return 404).

Key Types#

`keyType`	Prefix	Scope	Use
`standard` (default)	`api-`	Merchant	Server-side REST integrations and the WooCommerce plugin
`sdk_public`	`lpk_live_`	Merchant	Browser embed key for `auxVault.js` checkout only — not for plugins or servers; origin allow-list (optional here, required by the dashboard)
`processing`	`lv_pk_`	Merchant	Payment operations for one merchant gateway (`gatewayId`)
`token_processing`	`ltk_`	Merchant	Server-side PCI token processing; requires an IP allow-list
`erp`	`lv_erp_`	Tenant	Tenant-wide ERP integration; pass `X-Merchant-ID` per request

Merchant users may create only standard and sdk_public keys. The other types, and any tenant-scoped key, require an administrator (403 otherwise).

Create API Key#

POST/api/v1/api-keys

Create API Keybash

curl -X POST https://uat.auxcore.net/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "8f3c2a1e-5b7d-4e9a-9c1f-2d6e8a4b7c30",
    "name": "Production Key",
    "keyType": "standard",
    "expiresInDays": 365
  }'

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Display name
`merchantId`	uuid	Yes for merchant-scoped keys	Merchant the key belongs to
`keyType`	enum	No	`standard` (default), `sdk_public`, `processing`, `token_processing`, `erp`
`scope`	enum	No	`merchant` (default) or `tenant`. `erp` keys are always `tenant`.
`description`	string	No
`expiresInDays`	number	No	Key expires this many days after creation. Omit for no expiry.
`allowedOrigins`	string[]	No	`sdk_public` only. Origins allowed to use the key, e.g. `https://shop.example.com`. Empty = any origin.
`allowedServerIps`	string[]	`token_processing` only	Static egress IPs allowed to call the vault. At least one is required.
`gatewayId`	uuid	No	`processing` only: the merchant gateway the key is bound to
`permissions`	string[]	No	Stored with the key. Not currently enforced by the API gateway.

Response (201 Created):

Create API Keyjson

{
  "success": true,
  "data": {
    "apiKey": {
      "id": "5e8b1c3d-9a2f-4d7e-b6c0-1f4a8e2d9b57",
      "tenantId": "your-tenant-id",
      "merchantId": "8f3c2a1e-5b7d-4e9a-9c1f-2d6e8a4b7c30",
      "scope": "merchant",
      "keyType": "standard",
      "keyPrefix": "api-Xk3mP9qL",
      "name": "Production Key",
      "isActive": true,
      "expiresAt": "2027-01-28T12:00:00.000Z",
      "createdAt": "2026-01-28T12:00:00.000Z"
    },
    "plainKey": "api-Xk3mP9qLr2Tw8Vn4Bz6Yc1Hd5Fj"
  }
}

⚠️ Save this key! plainKey is only returned on creation (and on regenerate). Only sdk_public keys can be shown again later, because they are meant to be public.

List API Keys#

GET/api/v1/api-keys

Query	Default	Description
`merchantId`	caller's merchant	Filter to one merchant (must be in the caller's scope)
`includeLocations`	`false`	`true` also returns keys of the caller's locations
`keyType`	—	Filter by key type
`gatewayId`	—	Filter by gateway
`isActive`	—	`true` / `false`
`page`	`1`
`limit`	`50`

Response: { "success": true, "data": [ ... ], "meta": { "page": 1, "limit": 50, "total": 3 } }. Each key includes a maskedKey such as api-Xk3mP9qL••••••••••••; the secret is never returned.

Get API Key#

GET/api/v1/api-keys/:keyId

Update API Key#

PATCH/api/v1/api-keys/:keyId

Update API Keyjson

{
  "name": "Storefront SDK key",
  "allowedOrigins": ["https://shop.example.com", "https://www.example.com"]
}

name: non-empty, max 255 characters. description: max 1000 characters.
allowedOrigins applies to sdk_public keys only; values are lower-cased and trailing slashes removed.
allowedServerIps applies to token_processing keys only and cannot be empty.

Regenerate API Key#

POST/api/v1/api-keys/:keyId/regenerate

Issues a new secret with the same prefix type; the old secret stops working immediately. Returns { apiKey, plainKey }.

Disable API Key#

POST/api/v1/api-keys/:keyId/disable

POST /api/v1/api-keys/:keyId/enable re-enables it.

Revoke API Key#

DELETE/api/v1/api-keys/:keyId

Permanently revokes (soft-deletes) the key. Returns { "success": true, "data": { "message": "API key deleted successfully" } }.

Using SDK Public Keys#

When an sdk_public key has allowedOrigins, every request must send an Origin or X-Merchant-Origin header that matches the list; otherwise the API returns 403 (Origin required / Origin not allowed). These keys are rejected on admin and internal paths. Use a standard key for server-to-server calls.

Need help? Contact support@auxcore.net