Authentication — Sublyra Developers

1. Create an API key

API keys are created per shop, inside the Sublyra admin. Each key gets a label so you can tell later which system uses it.

1 Open the Sublyra admin and go to Settings → Integrations.

2 Find the API keys card. Type a label you'll recognize later — warehouse-3pl, analytics-pipeline — and create the key.

3 The app shows the full key once, in the confirmation banner. Copy it immediately into your password manager or your integration's config.

The key is never shown again. Sublyra stores only the SHA-256 hash of your key — the plaintext is never persisted. If you lose it, revoke it and create a new one. This also means a database leak does not leak usable keys.

What a key looks like

Every key starts with the prefix cad_pk_ followed by 48 random hexadecimal characters:

cad_pk_9f2ab41c7d3e58f0a1b2c3d4e5f60718293a4b5c

In the key list, each entry shows its label, a short non-secret fingerprint (the first few characters, like cad_pk_9f2ab…), when it was created, and when it was last used — enough to tell keys apart without ever exposing them.

Plan availability. API keys require the Pro plan, or the API & webhooks add-on ($19.99/mo). On other plans the reference stays readable but calls are rejected.

2. Send the key

Send the key as a Bearer token in the Authorization header of every request:

curl https://app.sublyra.com/api/v1/subscriptions?limit=50 \
  -H "Authorization: Bearer cad_pk_your_key_here"

The header format is exactly Authorization: Bearer <key> — one space after the word Bearer, then the full key. A missing or malformed header gets a 401 with a WWW-Authenticate: Bearer response header, per the HTTP spec.

How to check it works: a valid key returns 200 with a JSON body shaped like { "data": [ … ], "page": { … } }. An invalid key returns 401 with a JSON error — the API never answers machines with an HTML error page.

3. What a key can (and can't) do

A key can	A key cannot
Read your shop's subscriptions, customers and subscription orders via `GET /api/v1/…` Identify your shop automatically — no shop parameter needed or accepted	Write anything — the API is read-only; every non-`GET` method returns `405` Read another shop's data — the key itself resolves to exactly one shop, so cross-shop reads are impossible by construction Touch your Shopify admin, theme or checkout — it only covers Sublyra's subscription mirror

Because keys are read-only and shop-scoped, the practical blast radius of a leaked key is "someone can read your subscription list" — still worth rotating promptly, but not a store-takeover credential.

4. Rotate and revoke

Rotation is a create-swap-revoke cycle. There is no downtime if you do it in this order:

1 In Settings → Integrations → API keys, create a new key with a clear label (e.g. warehouse-3pl-2026-09).

2 Deploy the new key to the system that uses it and confirm calls succeed — watch for 200 responses.

3 Back in the key list, click Revoke on the old key. Revocation is immediate: the next request with the old key gets a 401.

"Legacy — rotate" badge. Keys created before Sublyra introduced hash-only storage are badged Legacy — rotate in the list. They still authenticate, but you should rotate them through the cycle above so only hashed keys remain.

Use the last used timestamp in the key list as a safety check: if a key hasn't authenticated in months, it's probably safe to revoke without the swap step.

5. Authentication errors

All errors are JSON with a machine-readable code:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key. Generate one under Settings → Integrations."
  }
}

Status	Code	Cause → fix
`401`	`unauthorized`	Missing or malformed `Authorization` header → send `Authorization: Bearer cad_pk_…` exactly.
`401`	`unauthorized`	Unknown key (typo, revoked, or created on a different shop) → create a fresh key under Settings → Integrations and update your integration.

A sudden wall of 401s after a rotation means some system still has the old key — check every place the key was deployed before assuming the new key is broken.

6. FAQ

How many keys can I have?

Create one per external system, labelled clearly — a 3PL, an analytics warehouse, an internal dashboard. Separate keys mean you can revoke one integration without touching the others, and the last-used timestamps tell you which system is actually talking.

Where should I store the key?

In your integration's secret store or environment variables — never in source control, never in client-side code, never in a browser. The key is a password; the cad_pk_ prefix makes it easy for secret-scanning tools to catch accidental commits.

Does the key expire?

No. Keys stay valid until you revoke them. Rotate on your own schedule — and immediately if you suspect a leak.

Where do I find the endpoints to call?

In the API reference — three resources, cursor pagination, full response shapes and error codes.