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
| Task | Interface | Access boundary |
|---|---|---|
| Connect another system to store data | REST /api/v1 | Store-scoped API key and explicit permissions |
| Work inside the signed-in administration application | tRPC | Application session and its access rules |
| Connect an AI assistant | MCP | Connected 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/themes | Expected handler response |
|---|---|
| No Authorization header, empty key or unknown key | 401, unauthorized |
| Recognised but revoked/inactive or expired key | 403, permission_denied |
Active, store-scoped key with only catalog:read | 403, permission_denied, missing themes:read |
Active, store-scoped key with themes:read | May 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.