Get your API keys

Flightdeck has two credential types, and which one you hold decides what you can do:

A merchant credential (fdk_...) is a tenant-scoped bearer key. The tenant it acts on and the scopes it may use are carried by the key itself. Send it as Authorization: Bearer fdk_....
A storefront token is the narrow credential that authorizes checkout and a shopper’s own reads. It is an opaque secret (no fixed prefix), provisioned by the platform operator; platform-wide today. Send it as x-storefront-token: <token> (consumer env var FLIGHTDECK_STOREFRONT_TOKEN).

Both are secrets. Keep them server-side. This guide covers minting and scoping merchant keys; storefront tokens are covered at the end.

Prerequisites

A merchant key that already holds manage:own_credentials (your first self-minted key does, once your store is live — see Create your store).

The scope model

Scopes come from a closed allowlist. A request for any scope not on the list is rejected — you cannot invent one. Scopes follow a read: / write: / manage: prefix over an own_<surface> noun. The full set today:

Scope	Grants
`read:own_store` / `write:own_store`	Read / edit store settings and site manifest
`read:own_catalog` / `manage:own_catalog`	Read catalog / create and edit products, variants, pricing
`read:own_orders` / `manage:own_orders`	Read orders / refund and cancel them
`manage:own_webhooks`	Outbound webhook subscriptions
`manage:own_domains`	Custom-domain claims
`manage:own_media`	The media/asset library
`manage:own_fulfillment`	The pick/pack/ship queue
`manage:own_inventory`	Vendors, purchase orders, receiving
`manage:own_marketing`	Drip and broadcast campaigns
`manage:own_fraud`	The store’s ban blocklist
`manage:own_store_credit`	Read and grant store credit
`manage:own_subscriptions`	Cancel / pause / resume subscriptions
`manage:own_giftcards`	Issue, list, void gift cards
`manage:own_returns`	The RMA queue
`manage:own_analytics`	Read-only reporting rollups
`read:own_billing`	Read the tenant’s B2B invoices
`read:own_customers`	Read the customer list and profiles
`read:own_affiliates` / `manage:own_affiliates`	Read affiliates / approve commissions
`manage:own_credentials`	List, mint, and revoke API keys

Read and act are split on purpose. read:own_orders can never move money — refunds and cancels require manage:own_orders. Give an integration the narrowest pair it needs.

Mint a scoped key

Choose the least privilege

Decide the smallest scope set the integration actually needs. A CI job that only reads the catalog should get ["read:own_catalog"], nothing more.

Issue the key

Issuance is subset-gated: a key can only mint a key whose scopes its own grant already includes. This means key management can never become privilege escalation.

curl -X POST https://api.ruo.pro/v1/my/credentials \
  -H "Authorization: Bearer fdk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "label": "ci-reader", "scopes": ["read:own_catalog"] }'

A 201 returns { "credential": { "id", "key", "label", "scopes" } }. The plaintext key appears once and is never retrievable again — only its hash is stored. If any requested scope exceeds the issuing key’s own grant, you get a 403 scope_escalation naming the exact offending scopes.

List your keys

The list returns metadata only — never key material, and revoked rows are included (revocation is a recorded state, not a delete). There is no lastUsedAt: the platform does not track it, so it is not invented.

curl https://api.ruo.pro/v1/my/credentials \
  -H "Authorization: Bearer fdk_your_key_here"

Revoke a key

Revocation is recorded, never a hard delete. Revoking your own key is allowed as a legitimate last action — the response says selfRevoked: true and your next request will 401.

curl -X POST https://api.ruo.pro/v1/my/credentials/{id}/revoke \
  -H "Authorization: Bearer fdk_your_key_here"

A 200 returns the revoked credential plus alreadyRevoked and selfRevoked flags. An already-revoked row answers 200 with alreadyRevoked: true — the end state holds; nothing changed now.

Storefront tokens

The storefront token is the narrow credential that authorizes checkout and a shopper’s own reads. It is an opaque secret (no fixed prefix), provisioned by the platform operator; platform-wide today — there is no self-serve mint route for it in the merchant API. Set it as FLIGHTDECK_STOREFRONT_TOKEN in your consumer’s environment and send it on its own header:

curl -X POST https://api.ruo.pro/v1/tenants/nova-peptide/checkout \
  -H "x-storefront-token: $FLIGHTDECK_STOREFRONT_TOKEN" \
  -H "Idempotency-Key: cart-8c1f2a:attempt-1" \
  -H "Content-Type: application/json" \
  -d '{ "customer_ref": "guest:jane@example.com", "items": [{ "variant_id": "var_123", "quantity": 1 }] }'

⚠️

Never ship either credential in browser code. The fdk_ key can manage your whole store; the storefront token can place orders. Build both server-side.

Authentication — the full credential and header model.
Create your store — where your first key comes from.
Handle errors — reading scope_escalation and 401 bodies.

Create your store Add products