---
title: "REST API v400 quickstart"
description: "Authenticate Ordering.co API v400 requests, fetch the latest five orders, paginate results, and distinguish REST credentials from MCP permissions."
canonical: https://docs.ordering.co/docs/developers/rest-api/
---

# REST API v400 quickstart

Use the public [OpenAPI specification](https://docs.ordering.co/assets/files/openapi-7d14972ed7240953948854a6b83beb4b.json) as the contract for paths, parameters, schemas, and authentication. The [API Reference](https://docs.ordering.co/api-reference/) presents that contract interactively. Requests reach your selected project's real data; begin with reads.

## Project, language, and authentication

The base URL is `https://api.ordering.co/v400/<language>/<project>`. Use your project's actual code and language, such as `en`; the example `demo` in the specification does not identify your project or provide a sandbox. A wrong project code cannot be corrected by changing credentials.

Create a REST API key in the Dashboard's API Keys settings. The public [developer quickstart](https://github.com/Ordering-co/ordering-dev-quickstart) sign-in page can deliver a separate REST key when you select **Also give my agent the REST API**. Cloning the helper does not require GitHub membership; access to project data still requires your own Ordering account and consent.

Inspect each operation's `security` block:

| Security scheme                 | Credential                                                                |
| ------------------------------- | ------------------------------------------------------------------------- |
| `apiKeyAuth`                    | REST API key in `X-Api-Key`. Never put it in `Authorization`.             |
| `bearerAuth`                    | Session JWT from `POST /auth` in `Authorization: Bearer <session token>`. |
| Empty operation security (`[]`) | Public operation; no credential required.                                 |

An MCP key cannot authenticate REST requests. API keys have no MCP read/write scope and do not expire; they act with your permissions until revoked. Keep keys on the server in environment variables or a secret manager, outside browser/mobile bundles and version control. Do not log authorization headers or customer responses.

## Get the latest five orders

`GET /orders` accepts API-key or session authentication. Without `mode=dashboard`, the operation scopes results to the caller's customer orders. Dashboard mode applies the operational user's role permissions; it does not bypass access checks. The quickstart's current example orders by descending ID:

```bash
# In an authorized quickstart checkout; the helper reads its local credentials.
./ordering api GET "/orders?orderBy=-id&page=1&page_size=5&mode=dashboard"
```

For a server integration, provide `ORDERING_API_KEY`, `ORDERING_PROJECT`, and `ORDERING_LANGUAGE` in its private environment. The following Node.js example makes one read without hardcoded credentials:

```javascript
const { ORDERING_API_KEY, ORDERING_PROJECT, ORDERING_LANGUAGE } = process.env;
if (!ORDERING_API_KEY || !ORDERING_PROJECT || !ORDERING_LANGUAGE) {
  throw new Error('Set API key, project code, and language in the server environment');
}
const base = `https://api.ordering.co/v400/${encodeURIComponent(ORDERING_LANGUAGE)}/${encodeURIComponent(ORDERING_PROJECT)}`;
const url = new URL(`${base}/orders`);
url.search = new URLSearchParams({
  orderBy: '-id', page: '1', page_size: '5', mode: 'dashboard',
}).toString();
const response = await fetch(url, {
  headers: { 'X-Api-Key': ORDERING_API_KEY, Accept: 'application/json' },
});
const body = await response.json();
if (!response.ok || body.error) {
  throw new Error(`Ordering request failed (HTTP ${response.status})`);
}
const orders = body.result;
```

Inspect the [List Orders contract](https://docs.ordering.co/api-reference/guides/get-orders/) for operation-specific inputs. Descending ID is the documented quickstart ordering; it does not guarantee sorting by a separate business date. An empty result can be valid. Avoid publishing customer data as setup evidence.

## Pagination, fields, and filters

List support varies by operation. Check its parameters before using `page` (starting at 1), `page_size`, `orderBy`, `params`, or `where`. `orderBy=-id` means descending ID. `params` selects supported fields; invalid selections can return all fields, so do not rely on it as a security boundary. `where` is a JSON filter over declared filterable fields; inspect the resource's `x-ordering-whereable` schema extension rather than inventing field names or operators.

Read the response's `pagination` block when present before requesting the next page. Do not combine page-based pagination with legacy `limit`/`offset`/`start` unless the operation documents that combination. See [Pagination](https://docs.ordering.co/api-reference/guides/pagination/). Check both HTTP status and the envelope's `error` flag. For `429`, back off and retry later rather than looping without a limit.

## MCP read/write permissions and REST changes

[MCP setup](https://docs.ordering.co/docs/developers/mcp/) connects an AI client with a separate personal key. Start with `read`: discover an operation with `search_operations`, inspect it with `describe_operation`, and call `read_operation`. Only a `write` key exposes `write_operation`, and only for the supported catalog and fields. Neither scope grants arbitrary REST access.

There is no implicit approval to change real data. Before a write, identify the project, target, method and exact changes, and obtain the user's explicit confirmation. With the quickstart, non-GET REST calls require that confirmation before using `./ordering api --yes`. After an uncertain write result, read the target before retrying. Revoking a REST API key and revoking an MCP key are separate operations.