Managing API keys

API keys authenticate every integration request. One partner can have several keys — one per environment, per team, or per rotation window. Keys may also exist without a partner — see Pass-through keys below.

Create keys from Settings → Integrations → Partners → {partner} → API keys, or from Settings → API Keys for partner-less (pass-through) keys.

Recommended practice

• One key per environment. Separate staging and production keys. Never reuse.
• Scope tightly. Grant only the resources a key needs — a sync job that only pushes inventory doesn't need integrations.orders.*. See Scopes.
• Set an expiration. Rotate at least once a year. Annual rotation forces the operator to revisit who actually uses the key.
• Store in a secret manager. Treat the key string like a password. It's only shown once at creation.
• Rotate immediately if a key is suspected of exposure. Revoking takes effect on the next request.

What a key holds

Field	Purpose
name	Human label. Shown in usage logs.
scopes	List of scope strings. See Scopes.
expires_at	Optional. Once past, requests return 401.
is_active	Revoke without deleting — flip to false.
Partner link	Optional. When set, responses and errors use the partner's field names; when unset, the key runs in pass-through mode.

Rotating a key

1. Create the new key with the same scopes.
2. Deploy it to the integrating system.
3. Verify traffic is flowing under the new key (see Integration Logs).
4. Revoke the old key.

Overlap briefly; don't flip in one step.

Revoking

Either:

• Set is_active = false — immediate, reversible.
• Delete the key — immediate, irreversible; old references to the key string become unrecoverable.

Using the key

curl https://<your-tenant>.datamingle.ai/api/integrations/v1/orders/ \
  -H "X-API-Key: sk_live_..."

See Authentication for failure-mode reference.

Pass-through keys

A key without a linked partner works against the raw platform schema:

• Payloads must use internal field names — no mapping applied.
• Responses and validation errors come back in internal field names.
• URL identifiers use the platform default per resource (order_number, sku, code).
• Every request is still logged; the log entry's partner column is empty and api_key identifies the caller.

Use pass-through keys when the integrating system already speaks the platform schema — a first-party service, an internal script, or a development tool. If you need field translation, link the key to a partner with a field mapping — see Custom Integrations.