YOUR FIRST API CALL

Getting started

Start a synthetic demo shop, sign in, then call an operation. The reference tells you what is implemented and who can use it.

Choose your environment

Mock

Your machine

Base URL: http://127.0.0.1:3000

Deterministic demo data. Test tokens are accepted only when the local server enables stub auth.

Live

Your verified host

Use the base URL supplied by your team for its live or staging environment.

Enter your verified HTTPS origin in Try it. Mock tokens are not valid there.

Start the local services and synthetic seed as described in the quickstart, then run Core in mock mode:

N1_API_MODE=mock N1_DEV_AUTH=stub \
DOCS_ORIGINS=http://localhost:4321,http://127.0.0.1:4321 pnpm dev

Mock badges describe approved contracts served with synthetic data. Live badges identify implemented operations. Mock mode is refused in production.

Sign in and keep the Bearer token

Use the generated demo login example. The request panel can sign into the mock server for you and keeps the returned token in this browser tab, bound to the environment and audience.

curl -X POST 'http://127.0.0.1:3000/auth/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{"identifier":"asha@demo-shop.example","password":"demo-password-1"}'

Open the login operation →

Send Authorization: Bearer <token> for authenticated operations. Tokens carry the shop and roles; request fields cannot change that. Read authentication for audience-specific endpoints and real sign-in.

Make your first authenticated call

Use the session query to confirm the audience, shop and roles the server sees. Choose Mock in Try it, sign in, and run the generated example.

curl -X POST 'http://127.0.0.1:3000/graphql' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"query":"query Session {\n  session {\n    audience\n    tenantId\n    userId\n    roles\n  }\n}","variables":{}}'

See the generated response

{
  "data": {
    "session": {
      "audience": "app",
      "tenantId": "0192f0c1-0000-7000-8000-00000000000a",
      "userId": "0192f0c1-0000-7000-8000-0000000000a1",
      "roles": [
        "owner"
      ]
    }
  }
}

Try the session query →

Integrate safely

Keep one key per action

A key you generate once per user action (a UUID). Retrying with the same key never applies the change twice.

The request panel preserves its key on retries. Use New action to create a fresh key when the user starts a different action. After a timeout, retry a write with the same key.

Page through lists

Connection lists accept first and after, and return totalCount and pageInfo.endCursor. Pass the last cursor to fetch the next page; see response handling.

Open the generated customers pagination example →

Branch on the error code

REST errors use the error envelope; GraphQL errors carry the same stable code in extensions. Show your own user-facing message and keep the request ID for diagnosis.

{
  "data": null,
  "errors": [
    {
      "message": "Sign in again.",
      "extensions": {
        "code": "UNAUTHENTICATED",
        "message": "Sign in again.",
        "requestId": "0192f0c1-7a3e-7c11-9f0e-5b2d8c1e4a90"
      }
    }
  ]
}

The complete error-code table comes from the generated catalogue.

Build the next screen

Browse the API reference, check its status and permissions, then copy a generated request or use Postman. The changelog records contract changes; versioning explains compatibility.