---
title: "Alakaʻi mea hoʻomohala"
description: "Ka REST API a Quire, OAuth, nā webhook, ke kikowaena MCP, a me nā hoʻonui."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/haw/llms.txt
> Use this file to discover all available pages before exploring further.

# Alakaʻi mea hoʻomohala

<span id="developer-guide"></span>

E hoʻohana i ka helu wahi API o kāu hui a me kahi palapala hōʻoia i kaupalena ʻia i nā laulā e pono ai. E hoʻomaka me noi heluhelu, nānā i ka pane, a mālama i nā ʻōlelo huna ma waho o ka mana code a me nā laʻana palapala.

Hoʻokahi API lehulehu ko Quire: REST ma luna o HTTPS, i wehewehe ʻia e palapala OpenAPI 3.1, me nā webhook pūlima no nā hanana a me ke kikowaena MCP no nā kōkua AI. Papa inoa ke [kuhikuhi API](https://docs.quirelms.com/api/) i kēlā me kēia endpoint a hanana.

## Nā helu wahi <!--quire:addresses-->

Loaʻa i kēlā me kēia hui kona helu wahi ponoʻī, a aia ka API ma lalo iho:

```
https://acme.quirelms.com/api/v1/courses
```

Hoʻoholo ka palapala hōʻoia i ka hui. Hōʻole ʻia ke kī no kekahi hui ke hoʻohana ʻia ma ka helu wahi o kekahi hui ʻē aʻe.

Hāʻawi ʻia ka palapala OpenAPI ma `/api/v1/openapi.json` ma ka helu wahi o kēlā me kēia hui, i ʻike mau ai nā mea hana client i ka mana āu e kāhea nei.

## Hōʻoia komo <!--quire:authentication-->

No nā script a me nā hoʻohui kikowaena-i-kikowaena nā **kī API**. Hana kekahi luna hoʻomalu i kī ma `/admin/integrations/api-keys`, koho i nā laulā, a ʻike hoʻokahi wale nō iā ia. E hoʻouna iā ia ma ke ʻano he token bearer:

```
curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50
```

Hoʻomaka nā kī me `qk_live_` a i ʻole `qk_test_`. E hāʻawi i kī ponoʻī i kēlā me kēia hoʻohui.

No nā polokalamu e hana ana ma ka inoa o kekahi kanaka i komo, ʻo **OAuth 2.1**. E hoʻopaʻa i client ma `/admin/integrations/oauth-clients`, a laila e hoʻohana i ke kaʻina code ʻae me PKCE (`/oauth/authorize`, `/oauth/token`), a i ʻole nā palapala hōʻoia client no ka client mīkini. Aia ka ʻike ʻike ma `/.well-known/oauth-authorization-server`. Hoʻēmi kahi laulā i nā hana a kahi token; ʻaʻole loa ia e ʻae iā ia e hana i nā mea i hiki ʻole i ke kanaka.

ʻO nā laulā `resource:read`, `resource:write`, a me `resource:delete`, e laʻa me `courses:read` a i ʻole `enrolments:write`. He ʻehā laulā mana kiʻekiʻe, i hōʻike ʻia me ka ʻōlelo aʻoaʻo ma ka pale ʻae: `audit:read`, `roles:write`, `tenants:write`, a me `users:delete`.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-api-keys.webp" alt="The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another." width="944" height="700" loading="lazy" decoding="async"><figcaption>API keys list who each key acts as and what it may reach.</figcaption></figure>

## Nā noi <!--quire:requests-->

- **Hoʻokaʻawale ʻaoʻao**: hoʻohana nā papa inoa a pau i nā cursor. E hoʻouna iā `limit`, a laila i ka `next_cursor` mai `page` ma ke ʻano he `cursor` ke ʻoiaʻiʻo ʻo `has_more` (laʻana ma lalo). ʻAʻohe offset.
- **Nā hoʻololi mai**: hoʻihoʻi ʻo `updated_since` i nā mea i hoʻololi ʻia ma hope o kekahi manawa. Hoʻohui iā `include_deleted=true`, a heluhelu paha iā `/<resource>/deletions`, e ʻike i nā mea i wehe ʻia.
- **Nā ID waho**: ʻae ka hapa nui o nā kumuwaiwai i kāu `external_id` ponoʻī, a heluhelu a hana-hou paha ʻo `/<resource>/ext:{external_id}` ma muli ona; no laila ʻaʻole pono ka lōkahi e mālama i nā ID Quire.
- **Hana hoʻokahi wale nō**: e hoʻouna i poʻo `Idempotency-Key` ma nā noi `POST`, `PATCH`, a me `DELETE`. Hoʻihoʻi ka hoʻāʻo hou ʻana me ke kī like i ka pane mua, ʻaʻole hana pālua i ka hana. Pono nā endpoint pūʻulu iā ia.
- **Nā mana**: aia ka mana nui ma ke ala (`/v1`). Ma loko ona, he hoʻoponopono lā ko kēlā me kēia hoʻololi haki, i koho ʻia ma ke poʻo `Quire-Version`, e laʻa me `Quire-Version: 2026-09-20`. Me ka ʻole o ke poʻo, loaʻa iā ʻoe ka hoʻoponopono e kū nei i ka wā i hoʻopuka ʻia ai kāu palapala hōʻoia.

He ʻaoʻao o kahi papa inoa:

```
{"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}}
```

## Nā hewa <!--quire:errors-->

He palapala pilikia RFC 9457 kēlā me kēia hewa:

```
{"type": "https://quire.com/errors/enrolment.seat_limit_reached",
 "title": "Seat limit reached", "status": 409,
 "code": "enrolment.seat_limit_reached", "category": "conflict",
 "detail": "The course has no seats left, so this enrolment was not created. ...",
 "request_id": "01JB7XQK4Z..."}
```

E nānā i `code`, no ka mea paʻa ia; ua kākau ʻia `detail` no nā kānaka, palekana ke hōʻike iā lākou, a hiki ke loli. Inā ʻaʻole ʻoe i ʻike i kekahi code, e hoʻokaʻawale ma ka `category`:

| Māhele | Kūlana | Hoʻāʻo hou |
| --- | --- | --- |
| `validation` | 422, me nā kikoʻī kahua ma `errors` | ʻAʻole |
| `authentication` | 401 | ʻAʻole |
| `authorization` | 403 | ʻAʻole |
| `not_found` | 404 | ʻAʻole |
| `conflict` | 409 | I kekahi manawa |
| `precondition` | 412 | ʻAʻole |
| `quota` | 402 no ka hoʻolālā, 413 no ka nui | ʻAʻole |
| `rate_limit` | 429, me `Retry-After` | ʻAe |
| `upstream` | 502 a i ʻole 504 | ʻAe |
| `internal` | 500 | ʻAe |

E haʻi i `request_id` ke hoʻokaʻaʻike ʻoe i ke kōkua.

## Nā webhook <!--quire:webhooks-->

E kau inoa ma `/admin/webhooks`, a i ʻole ma o ka API ma `/webhook_subscriptions`. E koho i nā hanana ma ka inoa (`enrolment.created`), ma ka māhele (`enrolment.*`), a i ʻole nā mea a pau (`*`). Hoʻouna mua ʻo Quire i `webhook.ping`; hoʻomaka ke kau inoa ke pane kāu endpoint iā ia.

Hahai nā hoʻouna i ka ʻōlelo kuhikuhi Standard Webhooks:

```
POST /hooks/quire
webhook-id: 01JB7XQK4Z8FQ2M3N4P5R6S7T8
webhook-timestamp: 1790000000
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
```

No ka hōʻoia ʻana i kahi hoʻouna:

1. Kūkulu i ke kaula `{webhook-id}.{webhook-timestamp}.{raw body}` mai nā byte pololei i loaʻa, ma mua o ka wehewehe ʻana i kekahi JSON.
2. E helu iā HMAC-SHA256 ma luna ona me ka ʻōlelo huna kau inoa, a hoʻolilo iā base64.
3. Hoʻohālikelike i nā waiwai `v1,` a pau ma `webhook-signature` me ka manawa kūlike mau. Hiki ke loaʻa ʻelua i ka wā hoʻololi kī ʻōlelo huna; kūpono kekahi kūlike.
4. Hōʻole i ka helu manawa i ʻoi aku ma mua o ʻelima minuke mai kāu uaki.

```
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, id, timestamp, rawBody, header) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', Buffer.from(secret.replace(/^whsec_/, ''), 'base64'))
    .update(`${id}.${timestamp}.${rawBody}`).digest();
  return header.split(' ').some((part) => {
    const [version, value] = part.split(',');
    const given = Buffer.from(value ?? '', 'base64');
    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
  });
}
```

Kāohi i ka hana pālua ma o `webhook-id`: hiki i kekahi hoʻouna ke loaʻa ma mua o hoʻokahi manawa. Lawe ke kino i nā ID a me ka hōʻuluʻulu pōkole; kiʻi i ke kumuwaiwai no kona kūlana o kēia manawa. Hoʻāʻo hou ʻia nā hoʻouna i hāʻule me ka hoʻokaʻawale manawa a hiki i 72 hola, a hiki ke hoʻokani hou ʻia mai ka moʻolelo hoʻouna.

## MCP <!--quire:mcp-->

Aia ke kikowaena MCP a Quire ma `/mcp` ma ka helu wahi hui, ma o HTTP hiki ke kahe. ʻImi kekahi client MCP i ke kikowaena OAuth mai `/.well-known/oauth-protected-resource`; komo a ʻae ke kanaka e like me nā client OAuth ʻē aʻe. Hana nā mea hana ma ke ʻano o kēlā kanaka me kona mau ʻae, a noi nā mea hana hoʻopōʻino i hōʻoia. Koho nā luna hoʻomalu i nā mea hana i loaʻa ma `/admin/integrations/mcp`.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-mcp.webp" alt="The AI assistants page with the server address to give an assistant and a table of the tools it can use." width="944" height="700" loading="lazy" decoding="async"><figcaption>AI assistants (MCP): the server address, and the tools an assistant may call.</figcaption></figure>

## Nā hoʻolālā a me ka API <!--quire:plans-and-the-api-->

Aia nā kī API, nā client OAuth, nā webhook, a me ke kikowaena MCP ma loko o ka ʻae API o ka hoʻolālā, a loaʻa ia i kēlā me kēia hoʻolālā maʻamau. Inā ʻaʻohe hoʻolālā iā ia, hōʻole ʻia ka hana kī, client, a kau inoa paha; hōʻole ʻia nā kākau REST a me nā pilina MCP; hoʻomau nā heluhelu REST i hiki ke hoʻokuʻu i ka ʻikepili. He palapala pilikia ka hōʻole me ke code `commerce.plan_entitlement`, ma ka māhele `precondition`.

## Nā hoʻonui <!--quire:extensions-->

Hoʻolaha ʻia nā ʻano hana, nā poloka, nā ʻano komo papa, nā ʻano komo, nā ʻano nīnau, nā hōʻike, nā poʻomanaʻo, a me nā hoʻohui ponoʻī a Quire ma o ka papa inoa hoʻonui like e hiki ai i kahi hoʻouka mālama ponoʻī ke hoʻonui. Hoʻopili ʻia nā hoʻonui i ke kūkulu ʻana: ʻaʻohe mea hoʻouka polokalamu i ka wā holo, ʻaʻole hoʻi hiki i kahi hui hoʻokipa ke hoʻohui i hoʻokahi. Hoʻā a hoʻopau nā luna hoʻomalu i kēlā me kēia hoʻonui no kā lākou hui ma `/admin/extensions` (e nānā i ke [alakaʻi luna hoʻomalu](/haw/admin/extensions/)).

No ke kākau ʻana i hoʻonui, e hoʻomaka me ka poloka laʻana a me ke poʻomanaʻo ma `packages/integration/extensions/src/sample.ts`. E koho i kahi hoʻonui a heluhelu i kāna ʻaelike ma `points.ts`; a laila e hoʻolaha i ka hoʻonui me ID, mana, laikini, nā mea e hāʻawi a koi ʻia ai, a me ke koho inā hiki i ka hui ke hoʻopau. E hoʻopaʻa inoa ma kahi e kūkulu pū ʻia ai ka polokalamu pūnaewele a me ka worker, i kūlike ai lāua. Nānā ka papa inoa i nā lula ponoʻī o kēlā me kēia wahi ke kūkulu ʻia a i kēlā me kēia kāhea iā `register`, hōʻole i kahi pūʻulu kūpono ʻole me ka inoa o kēlā me kēia pilikia, a mālama i ka papa inoa me ka loli ʻole ke hōʻole. Pono nā hoʻāʻo ponoʻī o ka hoʻonui e hōʻoia he nele ʻo `extensionContractProblems` no ia hoʻonui, a hoʻololi ka hoʻopau ʻana iā ia i ka mea e hoʻopā ʻia.

Source: https://docs.quirelms.com/haw/developer/index.mdx