Your first read-only API calls EN

Confirm the store, use minimal permissions and inspect themes without changing live data.

This guide is for a developer connecting a server-side integration. It follows the REST route contract, but has not been run against your account. Use an agreed test store and verify every result before moving on. It does not publish a theme or create an order, payment or webhook subscription.

Choose the right interface

TaskInterfaceAccess boundary
Connect another system to store dataREST /api/v1Store-scoped API key and explicit permissions
Work inside the signed-in administration applicationtRPCApplication session and its access rules
Connect an AI assistantMCPConnected user, store, active modules and agent policy

A REST API key is not a tRPC session. Do not copy a key into browser-side code, a public repository, screenshots or a support ticket.

1. Prepare a test credential

Ask the store administrator to confirm the test store ID or slug and the API base URL. Use a key with themes:read for the theme-list exercise, not * or write permissions. Module activation and permissions can limit available endpoints.

Load KADUNO_API_KEY from your secret store. Set KADUNO_API_URL to the confirmed API address without a trailing slash. Avoid typing the secret itself into a command recorded in shell history. The examples below are read-only; do not add activation or deletion requests to test access.

2. Confirm the store before reading more

curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${KADUNO_API_KEY}" \
  "${KADUNO_API_URL}/api/v1/store"

A successful response includes id, slug, name and storefrontUrl. Compare the ID or slug with the agreed test store. Stop if the store does not match, even if the response is 200. Do not share a real response containing internal store information in a public issue.

Illustrative success body, using invented store values rather than a captured response:

{
  "id": "example-store-id",
  "slug": "example-test-store",
  "name": "Example Test Store",
  "storefrontUrl": "https://shop.example.com"
}

The top-level fields follow the reviewed handler. The example ID is a placeholder, not an identifier to send back to the service. Your actual values will differ.

3. Read themes without modifying them

curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${KADUNO_API_KEY}" \
  "${KADUNO_API_URL}/api/v1/themes"

The response contains themes. An empty list is not an authentication failure. If a theme is active, record that status but do not use its slug as a target for a later write exercise. This endpoint does not use the same pagination shape as the product list. Follow each endpoint's own schema.

Illustrative success body for a store with no stored themes:

{
  "themes": []
}

This is a schema-backed example, not evidence that your store has no theme or that an authenticated call was performed. An empty stored-theme list does not establish what the storefront renders. For non-empty lists, inspect the returned records; do not assume a product-list pagination envelope.

The theme routes require themes:read and themes:write for their respective operations. The general permission list may omit these scopes; do not work around that documentation gap by granting *. Confirm the route contract and key setup with the administrator if the required scope is unavailable.

4. Check rejection and clean up

The reviewed authentication and route handlers define these expected responses. These are source expectations, not observed results from your deployment:

Read request to /api/v1/themesExpected handler response
No Authorization header, empty key or unknown key401, unauthorized
Recognised but revoked/inactive or expired key403, permission_denied
Active, store-scoped key with only catalog:read403, permission_denied, missing themes:read
Active, store-scoped key with themes:readMay reach the list handler if the other checks pass

themes:write is also accepted for these reads, but is unnecessary for this exercise. Do not use * to hide a missing-scope problem. Rate limiting occurs before route permission checks, so 429 can prevent an expected permission response; other infrastructure or release differences can also affect a result.

Illustrative missing-header response body (401):

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header. Use: Bearer <api_key>",
    "requestId": "example-request-401"
  }
}

Illustrative insufficient-permission response body (403):

{
  "error": {
    "code": "permission_denied",
    "message": "Missing permission: themes:read",
    "requestId": "example-request-403"
  }
}

The request IDs are invented. Record the actual status, error code and request ID privately when checking your environment; never record the Authorization header. If the deployed response differs, stop and investigate with the administrator. A documented expectation does not resolve an outstanding authentication defect. These requests do not test destructive or publication operations.

Revoke any temporary keys in administration when finished. unset KADUNO_API_KEY only clears a shell variable; it does not revoke the credential. If a secret is exposed, revoke it before continuing.

Contracts and failure handling

Use the API reference and OpenAPI document for fields, response shapes and pagination. An unfiltered platform reference is not a promise that every endpoint is enabled for your store.

For 401, check authentication. For 403, inspect the error code: key status, expiry, missing permission, store scope or an endpoint-specific module gate can be involved. These two theme read routes have no module gate in the reviewed source; other endpoints can have one. A 404 may mean a record is unavailable in the selected store. Respect Retry-After on 429; rate-limit headers can include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Do not automatically retry a write after a timeout: first establish whether the original operation completed. Use an endpoint's idempotency mechanism where one is provided. These read-only examples do not validate write idempotency.

Next: verify event signatures locally

The webhook signature exercise runs with synthetic data and no network requests. It explains why a valid signature is not enough to prevent repeated work.

The Norwegian receiver guide covers subscription setup and delivery handling. The integration directory helps you agree ownership and prerequisites before connecting systems.