API Kunci

Kunci API digunakan untuk mengautentikasi permintaan ke Capgo API. Setiap kunci dapat memiliki izin (mode) berbeda untuk mengontrol tingkat akses. Kunci bersifat khusus untuk organisasi dan harus dikelola dengan hati-hati karena memberikan akses ke sumber daya Capgo Anda.

Mode Kunci

baca: Hanya dapat membaca data, tidak diperbolehkan adanya modifikasi
unggah: Dapat membaca, memodifikasi, dan mengunggah bundel baru
tulis: Dapat membaca, mengubah data, dan mengunggah bundel
semua: Akses penuh ke semua operasi

Mode utama mengikuti skema bertahap/bertahap. Jika Anda memiliki kunci unggah, lalu Anda membuat kunci tulis, kunci tulis tersebut akan mampu melakukan segala sesuatu yang dapat dilakukan oleh kunci unggah. Silakan lihat diagram berikut untuk lebih memahami cara kerja kunci API.

Diagram yang menjelaskan cara kerja kunci API

Subkunci dengan Hak Terbatas

Anda dapat membuat subkunci dengan akses terbatas pada aplikasi atau organisasi tertentu. Hal ini berguna untuk membatasi akses ke sumber daya tertentu sambil tetap mengizinkan pengoperasian pada sumber daya lain. Gunakan parameter limited_to_apps dan limited_to_orgs saat membuat kunci untuk menentukan batasan ini.

Kunci Terenkripsi

Anda dapat membuat kunci API terenkripsi (hash) untuk meningkatkan keamanan. Saat membuat kunci terenkripsi:

Kuncinya di-hash menggunakan SHA-256 sebelum disimpan dalam database
Kunci biasa dikembalikan hanya sekali dalam respons pembuatan - segera simpan
Kunci tidak dapat diambil atau dilihat lagi setelah dibuat
Jika Anda kehilangan kunci terenkripsi, Anda harus membuat yang baru

Gunakan parameter hashed: true saat membuat kunci untuk mengaktifkan enkripsi. Ini adalah pendekatan yang direkomendasikan untuk lingkungan produksi.

Kedaluwarsa Kunci

Kunci API dapat memiliki tanggal kedaluwarsa untuk membatasi jangka waktu paparan jika kunci disusupi. Kapan tanggal kedaluwarsa ditetapkan:

Kunci berhenti bekerja setelah tanggal dan waktu yang ditentukan
Permintaan menggunakan kunci kadaluwarsa akan ditolak karena kesalahan
Kunci yang kedaluwarsa secara otomatis dibersihkan setelah 30 hari

Organisasi dapat menerapkan kebijakan kedaluwarsa:

Memerlukan masa berlaku habis: Semua kunci API harus memiliki tanggal masa berlaku
Periode kedaluwarsa maksimum: Membatasi seberapa jauh tanggal kedaluwarsa dapat ditetapkan di masa mendatang

Praktik Terbaik Keamanan

Prinsip Hak Istimewa Terkecil: Selalu gunakan mode paling ketat yang masih memungkinkan integrasi Anda berfungsi
Gunakan Kunci Terenkripsi: Buat kunci hash untuk produksi guna melindungi dari pelanggaran basis data
Tetapkan Tanggal Kedaluwarsa: Gunakan tanggal kedaluwarsa untuk membatasi masa pakai kunci Anda
Rotasi Reguler: Putar kunci API Anda secara berkala
Penyimpanan Aman: Simpan kunci API dengan aman dan jangan pernah memasukkannya ke kontrol versi
Pemantauan: Pantau penggunaan kunci API dan segera cabut kunci apa pun yang disusupi
Subkunci Terbatas: Gunakan subkunci dengan hak terbatas untuk integrasi tertentu guna meminimalkan risiko

Titik akhir

DAPATKAN

https://api.capgo.app/apikey/

Ambil semua kunci API yang terkait dengan akun Anda.

Jenis Respons

interface ApiKey {
  created_at: string | null
  id: number
  key: string | null  // null for encrypted keys
  mode: 'read' | 'write' | 'upload' | 'all'
  name: string
  updated_at: string | null
  user_id: string
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  expires_at?: string | null  // ISO 8601 date, null means never expires
}
```> **Catatan**: Untuk kunci terenkripsi, kolom `key` akan menjadi `null` dalam respons GET karena kunci biasa hanya ditampilkan satu kali selama pembuatan.

#### Contoh Permintaan

```bash
curl -H "authorization: your-api-key" https://api.capgo.app/apikey/

Contoh Respon

{
  "data": [
    {
      "id": 1,
      "key": "ak_123...",
      "mode": "read",
      "name": "CI/CD Read Key",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "user_id": "user_123"
    },
    {
      "id": 2,
      "key": "ak_456...",
      "mode": "upload",
      "name": "Deploy Bot",
      "created_at": "2024-01-02T00:00:00Z",
      "updated_at": "2024-01-02T00:00:00Z",
      "user_id": "user_123",
      "limited_to_apps": ["com.demo.app"]
    }
  ]
}

POSTINGAN

https://api.capgo.app/apikey/

Buat kunci API baru untuk organisasi tertentu.

Isi Permintaan

interface ApiKeyCreate {
  name: string
  mode: 'read' | 'write' | 'upload' | 'all'
  limited_to_apps?: string[]
  limited_to_orgs?: string[]
  hashed?: boolean       // Create an encrypted key (recommended for production)
  expires_at?: string    // ISO 8601 date for key expiration
}

Contoh Permintaan (Kunci Standar)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Limited Read Key",
    "mode": "read",
    "limited_to_apps": ["com.demo.app"]
  }' \
  https://api.capgo.app/apikey/

Contoh Permintaan (Kunci Terenkripsi dengan Kedaluwarsa)

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Secure CI Key",
    "mode": "upload",
    "hashed": true,
    "expires_at": "2025-06-01T00:00:00Z"
  }' \
  https://api.capgo.app/apikey/

Contoh Respon (Kunci Standar)

{
  "apikey": {
    "id": 3,
    "key": "ak_789...",
    "mode": "read",
    "name": "Limited Read Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "limited_to_apps": ["com.demo.app"]
  }
}

Contoh Respons (Kunci Terenkripsi)

{
  "apikey": {
    "id": 4,
    "key": "ak_abc123...",
    "mode": "upload",
    "name": "Secure CI Key",
    "created_at": "2024-02-12T00:00:00Z",
    "user_id": "user_123",
    "expires_at": "2025-06-01T00:00:00Z"
  }
}

Penting: Untuk kunci terenkripsi, nilai key dalam respons ini adalah satu-satunya saat Anda akan melihat kunci biasa. Simpan segera di lokasi yang aman. Permintaan GET berikutnya akan mengembalikan null untuk bidang key.

HAPUS

https://api.capgo.app/apikey/:id/

Hapus kunci API yang ada. Gunakan ini untuk segera mencabut akses.

Parameter

id: ID kunci API yang akan dihapus (pengidentifikasi numerik, bukan string kunci itu sendiri)

Contoh Permintaan

curl -X DELETE -H "authorization: your-api-key" https://api.capgo.app/apikey/1/

Respon Sukses

{
  "success": true
}

Kasus Penggunaan Umum

Integrasi CI/CD: Membuat kunci hanya-baca untuk pipeline CI guna memeriksa status penerapan
Otomasi Penerapan: Gunakan kunci mode unggah untuk skrip penerapan otomatis
Alat Pemantauan: Gunakan tombol mode baca untuk integrasi pemantauan eksternal
Akses Admin: Gunakan semua tombol mode secukupnya untuk alat administratif
Akses Terbatas: Membuat subkunci dengan hak terbatas pada aplikasi atau organisasi tertentu untuk integrasi pihak ketiga

Penanganan Kesalahan

Skenario kesalahan umum dan tanggapannya:

// Invalid mode
{
  "error": "Invalid mode specified. Must be one of: read, write, upload, all",
  "status": "KO"
}

// Key not found
{
  "error": "API key not found",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage API keys",
  "status": "KO"
}

// Expired API key used for authentication
{
  "error": "API key has expired",
  "status": "KO"
}

// Invalid expiration date (in the past)
{
  "error": "Expiration date must be in the future",
  "status": "KO"
}

// Organization requires expiration
{
  "error": "Organization policy requires an expiration date for API keys",
  "status": "KO"
}

// Expiration exceeds organization limit
{
  "error": "Expiration date exceeds organization maximum of 90 days",
  "status": "KO"
}