# API Keys me te Whakauru Kaihanga

Source: https://support.kapsulehost.com/mi-nz/developer-api-access

KapsuleHost e whakarato i a koe i rua ngā tohu kaiwhakaari: ngā Kī API kua whakaparua mō te pānui i tō pūkete mā te pokapū tuhinga, me te Pūtaka Waihanga Ararau e tere ake ai ngā waihanga Turborepo me Nx i runga i ō ake miihini me ngā kaiwhakahaere CI.

Ehara i te mea kua whakaahoatia i te mea ahakoa aha. Ko te huhua i hangaia mai i te **Settings**, a, ka hoatu e ia he huna kotahi tonu ki a koe.

## Te Waihanga Kī API

Ko ngā Kī API e noho ana i raro i te **Settings**, kātahi ko te **Security**, i roto i te **Ngā Kī API** kāri.

![Ngā Kī API kāri i roto i ngā tautuhinga whakaupoko KPanel me ngā tīpuna roanga e kitea ana](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. Haere ki te **Settings**, kātahi ko te **Security**.
2. Whakakau ki ngā **Ngā Kī API** me te pāwhiri i te **Kī hou**.
3. Tukuna he ingoa mō te kī. Ka tohu te āhuatanga "Ingoa kī (e.g. Taku arotake tūmataiti)". Ko te ingoa mō a koe anake, nō reira me kōrero i te wāhi e whakamahia ai te kī.
4. Pāwhiria ngā tīpuna roanga kia tohu ai he aha e mea ai te kī. E toru ngā roanga pānui i te tohu kē: `read:sites`, `read:email`, me te `read:domains`. Pāwhiria he tīpuna kia tāpiri ai, kia tangohia rānei.
5. Pāwhiri i te **Create**.

Ka puta te kī katoa i te tahi nei, i roto i he kīanga ātaahua "Kape inaianei". Kape atu e tika ana ki tō pūkete huna. Mēnā ka whakatīpako koe i tēnei kīanga, ka ngaro te kī: ko te waenui poto noa iho e pupuri ana, arā te mea katoa e taea ai te rārangi e whakaatu anō.

> **Warning:** E kore te kī e whakaaturia he tuarua me e kore rawa e taea te hokinga. Mēnā ka ngaro tō kī, whakakore tēnei kī me te waihanga he hou. Kaua e nekehia atu ki roto i he kōkupu tūpono, he pūrongo, he whakatāmuri, he kupu karere rānei.

Ko te **Owner** me te **Admin** noa iho ngā mahi e taea ai te waihanga kī. Ko ngā mahi kē atu ka whiwhi i te hapa whakaaetanga. Mēnā ka waihangaia he kī, ka tonoa he īmera tohu hepoinga ki te wahitau o te tangata nāna i waihanga, nō reira he mea take whānuitia te whakamātau tūturu.

## Ngā Roanga

E whitu ngā roanga e whakaratoa ana:

| Roanga | Whakaaetanga |
|---|---|
| `read:sites` | Te pānui i ngā pae tukutuku o ē |
| `write:sites` | Mokakitea mō te tukunga mahi i runga i ngā pae tukutuku |
| `read:email` | Te pānui i ō pūkete īmera |
| `write:email` | Mokakitea mō te tukunga mahi i runga i ngā pūkete īmera |
| `read:domains` | Te pānui i ō rohe |
| `write:domains` | Mokakitea mō te tukunga mahi i runga i ngā rohe |
| `read:billing` | Mokakitea mō te pānui i ngā raraunga utu |

> **Note:** Ko te API kaihoko he pānui noa tonu inanahi. Ko ngā roanga `write:` me te `read:billing` e taea ai te tohu ki he kī, heoi kaore inaianei he pokapū kaihoko e kai ana, nō reira ka whakaaetanga nei kore ake. Whakaaetanga noa i ngā roanga pānui e tika tonu ai koe me te whakahoki ki te kī mēnā ka tukua ngā pokapū tukunga.

## Te Whakamahi i te Kī

Tonoa te kī hei tohu kaiwhakaari i runga i te `Authorization` tūpono.

```sh
curl https://kpanel.kapsulehost.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

E toru ngā pokapū e whakaaetanga ai he kī API kaihoko:

| Pokapū | Roanga e hiahiatia ana | Ka whakahoki |
|---|---|---|
| `GET /api/v1/sites` | `read:sites` | Ō pae tukutuku, me te rohe, momo tūmataiti me te tohu |
| `GET /api/v1/domains` | `read:domains` | Ō rohe, me te tohu me te wā rongoa |
| `GET /api/v1/mailboxes` | `read:email` | Ō pūkete īmera |

Ko te tono kāore i te kī, i te kī e kore e mōhiotia, i te kī kua whakakorea rānei, ka whakahoki `401`. He kī tika kāore i te roanga tika e whakahoki `403` me he karere e ingoa nei te roanga i hiahiatia. Ko ia whakatutuki angitu ka whakabōwai i te wāmatatau whakamahi huamata o te kī.

> **Tip:** Hōnea ngāwari. Ko ēnei pokapū e pānui ana i ngā raraunga pūkete ora, a, he pukupuku taupuhipuhi ki a rātou he ōrite tonu ki te whakamahi kino. I te roherohe kotahi he nui tonu mō te āhuatanga e hiahia ai te papamata; i te haora kotahi he nui te nuinga.

## Te Āta Tirotiro me te Whakakorea i ngā Kī

Ko te tepu Ngā Kī API e rārangi ana i ia kī hohe i te **Ingoa**, **Waenui** (te ahuatanga kitea o te kī), me ngā **Roanga**. Pāwhiri i te **Revoke** i te mutunga o te rārangi kia whakamate ai.

> **Important:** Ko te whakakorea ka mahi tonu me kaore he arorau whakaapārangi. Ko te tono tuarua e whakamahi ana i tēnei kī ka rahua `401`. E kore e taea te hoki i he kī kua whakakorea, nō reira me matua mohio koe he aha e whakamahi ana i a ia i mua i te pāwhiri.

Ko ngā kī nō te **pūkete**, ehara i te tangata nāna i waihanga. Ko te tango i te hoa mahi i [te whārangi Rōpū](https://support.kapsulehost.com/mi-nz/account-team-members) e kore ai e whakakorea ngā kī i waihanga e ia. Whakatinihia he arotake kī i tō whakakorea: tango i te tangata, kātahi haere ki konei me te whakakorea i te mea nānā i waihanga.

Ko te waihanga me te whakakorea kī, e rua, e rego ana i te [loki arotake](https://support.kapsulehost.com/mi-nz/account-audit-log) i raro i ngā mahi `api_key.*`, me te kaiwhakaari me te wahitau IP i te putake.

## Te Pūtaka Waihanga Ararau

Ko te whārangi **Developer**, i roto i te rōpū Aronui o te rēti tautuhinga, e whakarato ana i he **Pūtaka Waihanga Ararau**. Ko te kīanga kāri he ara kia "Whakatupuranga Turborepo me ngā waihanga Nx ma te tukuwhiti pūtaka tonutanga puta noa i ngā miihini me ngā paipa CI."

1. Haere ki te **Settings**, kātahi ko te **Developer**.
2. Pāwhiri i te **Whakahohe pūtaka ararau**.
3. Kape te tohu i te kīanga "Tohu hou i waihanga. Kape inaianei, e kore e whakaaturia anō".

Kātahi, whakatakitaki i ngā taurangi taiao e rua i tō whiriwhiri arotake CI, i tō ake `.env.local` rānei:

```sh
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
```

Ko te ID rōpū ko tō kaute KapsuleHost, e whakaaturia ana i ngā tohu whakatakitaki i runga i te whārangi ano.

Ko te whārangi e kōrerohia ana te whakakotahi tonu: Turborepo 1.x me te nuinga ake, Nx 16 me te nuinga ake, me he taputapu e whakatupuranga ana i te kaupapa pūtaka ararau i te ōrite. Ko ngā mea waihanga e puritia ana i ia kaute, a, e kore rawa aua e tukua whānui puta noa i ngā kaute.

E rua ngā whakahaere kē atu e noho ana i te kāri:

- **Whakatupuranga tohu** ka whakaputauta he tohu hou a, whakakino i te kumatua. Ko ia mahi CI e kore e whakamahi i te pūtaka, nō reira whakatupuranga me te whakahou i ō katikati i tahi.
- **Disable** ka whakatū i te pūtaka katoa.

## Te Whiriwhiri Puta rua

E whakatika ana i ngā raru e kore e ōrite ana, a, e kore e taea te whakakape.

Whakamahia he **Kī API** mēnā me matua mohio he mea i waho atu i KapsuleHost he tohu o tō pūkete: he papamata tohu e rārangi ana i ō pae tukutuku, he tuhinga arotake e whakatupuranga ana mō ngā rohe e whakamate kē ana, he kaupapa i kawe i ngā mea.

Whakamahia te **pūtaka waihanga ararau** mēnā e tere kē ana ō waihanga nā te mea me waihanga anō e ia miihini, e ia rere CI rānei i ngā papaioio kore roa o te mea. E kore he hononga ki ō pae tukutuku kua whakatuu, a, e kore e pānui i ō raraunga pūkete.

## Te Whakatika Rapanga

**Ko ia tono ka whakahoki 401.** Whakatupato koe i te tonoa `Authorization: Bearer <key>` i te mokowā kotahi, kāore te kī i te tapahia mēnā i kapatia koe, a, kāore kia whakakorea. Whakataurite te timatanga o ō kī me te pou **Waenui** kia matua mohio koe ko te kī e whakamahi ana koe.

**Ko te tono ka whakahoki 403 e ingoa nei he roanga.** Kaore he roanga i te kī. Ko ngā roanga e tera ana mēnā ka waihangaia te kī, nō reira waihanga he whakakaupapa me ngā roanga tika me te whakakorea i te kumatua.

**E kore e taea e au te kitea i te Ngā Kī API kāri.** E noho ana i te whārangi Security, ehara i te whārangi Developer. Ko te whārangi Developer e pupuri noa i te pūtaka waihanga.

**Ko te pūtona Kī hou e kore he mahi.** Ko ō mahi i raro i Admin. Āwhina i te Owner i te Admin rānei.

**Kaore ngā waihanga e pakipaki ana i te pūtaka.** Whakatupato i te mea `TURBO_TOKEN` me te `TURBO_TEAM` kei te taiao waihanga, kāore te tohu i te whakatupuranga i muri i te whakatakitaki, a, ko te whārangi e whakaatu tonu i te tūhonotanga **Active**.

**He kī i waihanga e au kaore i te puta ake.** Me whakarite koe i te paheketanga. Whakakorea, kātahi me haere koe puta i [Account Security](https://support.kapsulehost.com/mi-nz/account-security) me te tirotiro i te [loki arotake](https://support.kapsulehost.com/mi-nz/account-audit-log) mō he aha kē atu i te puta.