# Cipta API token

> Cipta, lihat, copy dan delete API token BCL untuk laman web, aplikasi dan AI agent anda, pilih kebenarannya, dan urus aplikasi yang disambungkan.
>
> Source: https://docs.bcl.my/ms/api-tokens/

API token membolehkan laman web, aplikasi atau AI agent anda sendiri bekerja dengan akaun BCL anda tanpa password anda. Anda mencipta token dalam BCL dan memilih apa yang setiap token boleh buat. Hanya Admin boleh menciptanya.

Untuk endpoint dan format permintaan, lihat [rujukan API BCL](https://bcl.my/docs/api). Untuk menyambungkan pembantu AI, lihat [Sambungkan Claude atau ChatGPT kepada BCL](/ms/connect-ai-agent/) atau [Sediakan aplikasi AI lain](/ms/ai-agent-setup/).

## Di mana token berada

API token berada di page **Integrations**:

1. Di sidebar, pergi ke **Platform Setup** → **Integrations**.

   *(Screenshot: Menu Platform Setup di sidebar BCL, dengan Integrations ditanda)*

2. Buka tab **API Token**.

   *(Screenshot: Page Integrations dengan tab API Token ditanda)*

Tab ini ada dua bahagian: **API Tokens**, iaitu token anda sendiri, dan **Connected Apps**, iaitu aplikasi AI yang anda log masuk dengan OAuth.

## Cipta token

Setiap Admin boleh ada sehingga 10 token. Untuk mencipta satu token:

1. Pada tab **API Token**, klik **Create New API Token**.

   *(Screenshot: Bahagian API Tokens dengan butang Create New API Token ditanda)*

2. Dalam **Token Name**, masukkan tempat token itu akan digunakan, contohnya "Kopi Kampung Website". BCL mencadangkan satu nama, yang anda boleh tukar.
3. Di bawah **Permissions**, tandakan hanya apa yang aplikasi itu perlukan:

   | Kebenaran | Membolehkan token | Gunakannya untuk |
   |---|---|---|
   | **API Read** | Membaca form, transaksi, pelanggan, kupon dan data lain melalui API | Laporan, dashboard, sync pesanan ke sistem lain |
   | **API Write** | Mencipta payment link dan menukar data melalui API | Laman web atau aplikasi yang mencipta payment link atau mengemas kini form |
   | **MCP Read** | Membenarkan AI agent mencari data anda | Claude Code, Cursor, VS Code dan aplikasi AI lain |
   | **MCP Write** | Membenarkan AI agent mencipta dan menukar sesuatu | Aplikasi AI yang anda percayai untuk membuat perubahan |

   *(Screenshot: Panel Create New API Token dengan Token Name, senarai Permissions ditanda, dan Expiration)*

4. Dalam **Expiration**, pilih bila token itu berhenti berfungsi: **Never**, **30 days**, **90 days**, **180 days** atau **365 days**.
5. Klik **Create Token**. BCL memaparkan mesej `API token "<name>" has been created.` dan menambah token itu ke dalam senarai.

Kebenaran API dan kebenaran MCP adalah berasingan. Token dengan **API Read** dan **API Write** sahaja tidak berfungsi dengan AI agent, dan token MCP sahaja tidak berfungsi dengan API. **API Write** sahaja tidak boleh membaca, jadi tandakan **API Read** juga dalam kebanyakan kes. Anda tidak boleh menukar kebenaran token kemudian: cipta token baru sebagai ganti.

## Guna token

Token bermula dengan `bcl_`. Sistem anda menghantarnya dalam header `Authorization` bagi setiap permintaan:

```text
Authorization: Bearer bcl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json
```

API berada di `https://api.bcl.my/v1`. Hantar juga `User-Agent` anda sendiri, contohnya `MyShop/1.0`: BCL menolak permintaan daripada user agent default skrip seperti `curl` atau `python-requests` biasa. Setiap endpoint ada dalam [rujukan API BCL](https://bcl.my/docs/api).

Token nampak data yang sama seperti anda. Token milik Admin yang menciptanya, dan Admin lain tidak nampak token itu dalam senarai mereka.

## Lihat atau copy token semula

BCL menyimpan token anda, jadi anda boleh melihatnya semula kemudian. Dalam senarai **API Tokens**:

- Klik ikon **View token** (ikon mata) untuk memaparkan token di bawah namanya. Klik sekali lagi untuk menyembunyikannya.
- Klik ikon **Copy token** untuk copy token itu.

*(Screenshot: Senarai API Tokens, dengan ikon View token dan Copy token ditanda pada baris sesuatu token)*

Senarai ini juga menunjukkan **Abilities** setiap token, bila ia **Expires**, dan bila ia **Last Used**. Token yang sudah tamat tempoh memaparkan **Expired** di sebelah namanya dan tidak boleh dilihat atau di-copy lagi.

## Delete token

Delete token memutuskan akses setiap aplikasi yang menggunakannya. Untuk delete satu token:

1. Pada baris token itu, klik ikon **Delete token** (ikon tong sampah).
2. Dalam **Delete API Token**, klik **Delete Token**.

   *(Screenshot: Pengesahan Delete API Token dengan butang Delete Token ditanda)*

Mana-mana aplikasi yang menggunakan token itu hilang akses serta-merta. Token yang sudah di-delete tidak boleh dikembalikan. Jika aplikasi itu masih memerlukan akses, cipta token baru dan masukkan ke dalam aplikasi itu.

## Connected Apps

**Connected Apps** menyenaraikan aplikasi AI, seperti Claude, ChatGPT atau Cursor, yang anda sambungkan dengan log masuk menggunakan akaun BCL anda (OAuth). Aplikasi ini tidak menggunakan token. Untuk setiap aplikasi, anda nampak kebenarannya, bila anda meluluskannya dan bila ia terakhir digunakan.

*(Screenshot: Bahagian Connected Apps dalam tab API Token)*

Untuk memutuskan akses sesuatu aplikasi, klik ikon **Revoke access** pada barisnya, kemudian **Revoke Access**. Lihat [Putuskan sambungan aplikasi AI](/ms/connect-ai-agent/#putuskan-sambungan-aplikasi-ai).

## Tips

Token ialah keys kepada akaun anda. Beberapa tabiat ini memastikannya selamat:

- **Satu token untuk setiap aplikasi.** Namakan token mengikut aplikasi itu dan, untuk tool AI, komputernya. Jika satu token bocor, anda hanya delete token itu dan yang lain terus berfungsi.
- **Buang akses apabila staf berhenti.** Token dan aplikasi yang disambungkan milik Admin yang menciptanya, dan Admin lain tidak nampak semua itu. Minta Admin yang akan berhenti delete token mereka dahulu, dan gantikan mana-mana token yang mereka ada salinannya.
- **Jangan sekali-kali paste token di tempat awam.** Jangan letak token dalam kod laman web yang pelawat boleh lihat, repository Git awam, screenshot dan group chat. Jika sesuatu token terdedah, delete token itu dengan segera.
- **Tetapkan tarikh tamat.** Token dengan **Never** berfungsi sehingga seseorang delete token itu. Semak **Last Used** sekali-sekala dan delete token yang tiada siapa guna.

## Isu biasa

### Bagaimana saya mendapatkan API key untuk membina integrasi saya sendiri?

Pergi ke Platform Setup → Integrations, buka tab API Token dan klik Create New API Token. Tandakan API Read, serta API Write jika sistem anda mencipta payment link atau menukar data.

### Token saya hilang. Adakah saya perlu cipta token baru?

Tidak perlu. Pada tab API Token, klik ikon View token atau Copy token pada baris token itu. BCL menyimpan token itu supaya anda boleh melihatnya semula.

### Kenapa saya dapat "Token does not have the 'api:write' ability"?

Token itu dicipta tanpa API Write. Kebenaran tidak boleh ditukar kemudian, jadi cipta token baru dengan API Write ditandakan dan delete token yang lama.