Manajemen API Key

API key digunakan untuk mengautentikasi permintaan API Zeabur Email Anda. Setiap key dapat memiliki tingkat izin yang berbeda.

Jenis Izin

Zeabur Email menyediakan tiga tingkat izin:

Jenis Izin	Deskripsi	Contoh Penggunaan
Baca Saja (`read_only`)	Hanya dapat memeriksa email dan statistik	Analisis data, dashboard pemantauan
Kirim Saja (`send_only`)	Dapat mengirim email dan memeriksa status	Aplikasi production (disarankan)
Akses Penuh (`all`)	Mencakup semua izin operasi	Alat manajemen, environment pengembangan

⚠️

Demi keamanan, disarankan menggunakan izin “Kirim Saja” di production dan menghindari penggunaan “Akses Penuh”.

Membuat API Key

Masuk ke Konsol

Buka halaman manajemen Zeabur Email di konsol Zeabur.

Buat Key Baru

Buka “Kunci API”
Klik “Buat Kunci API”
Masukkan nama key (untuk identifikasi)
Pilih jenis izin
(Opsional) Batasi ke domain tertentu
Klik “Buat”

Simpan Key

🚫

Key hanya ditampilkan satu kali saat dibuat! Segera simpan di lokasi yang aman.

Setelah dibuat, sistem akan menampilkan API key secara lengkap. Salin dan simpan dengan aman — Anda tidak akan dapat melihatnya lagi.

Pembatasan Domain

Anda dapat membatasi API key agar hanya dapat mengirim email dari domain tertentu untuk meningkatkan keamanan:

// Atur domain yang diizinkan saat membuat key
{
  "name": "Production API Key",
  "permission": "send_only",
  "allowed_domains": ["yourdomain.com", "mail.yourdomain.com"]
}

Dengan begitu, meskipun key bocor, penyerang tidak dapat menggunakan domain yang tidak diizinkan untuk mengirim email.

Menggunakan API Key

Header Permintaan HTTP

Sertakan key di setiap permintaan API:

POST /api/v1/zsend/emails
Host: api.zeabur.com
Content-Type: application/json
Authorization: Bearer zs_your_api_key_here
 
{
  "from": "hello@yourdomain.com",
  ...
}

Contoh Kode

JavaScript

const apiKey = process.env.ZSEND_API_KEY;
 
const response = await fetch('https://api.zeabur.com/api/v1/zsend/emails', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + apiKey
  },
  body: JSON.stringify({
    from: 'hello@yourdomain.com',
    to: ['user@example.com'],
    subject: 'Test Email',
    html: '<p>Test Content</p>'
  })
});

Python

import os
import requests
 
api_key = os.environ.get('ZSEND_API_KEY')
 
response = requests.post(
    'https://api.zeabur.com/api/v1/zsend/emails',
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + api_key
    },
    json={
        'from': 'hello@yourdomain.com',
        'to': ['user@example.com'],
        'subject': 'Test Email',
        'html': '<p>Test Content</p>'
    }
)

Go

package main
 
import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)
 
func sendEmail() error {
    apiKey := os.Getenv("ZSEND_API_KEY")
    
    payload := map[string]interface{}{
        "from":    "hello@yourdomain.com",
        "to":      []string{"user@example.com"},
        "subject": "Test Email",
        "html":    "<p>Test Content</p>",
    }
    
    jsonData, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.zeabur.com/api/v1/zsend/emails", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer " + apiKey)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    return err
}

Rotasi Key

Melakukan rotasi API key secara berkala merupakan praktik keamanan yang baik:

Buat Key Baru

Buat API key baru sambil tetap mempertahankan key lama agar tetap aktif.

Perbarui Konfigurasi Aplikasi

Secara bertahap, ganti API key di aplikasi Anda dengan key yang baru.

Hapus Key Lama

Setelah memastikan semua aplikasi telah diperbarui, hapus key lama.

Disarankan untuk melakukan rotasi key setiap 90 hari.

Mencabut Key

Jika sebuah key bocor atau tidak lagi diperlukan:

Buka “Kunci API”
Temukan key yang ingin dihapus
Klik tombol “Hapus”
Konfirmasi penghapusan

⚠️

Setelah key dihapus, semua permintaan API yang menggunakan key tersebut akan langsung gagal.

Praktik Keamanan Terbaik

1. Gunakan Environment Variables

Jangan pernah menuliskan API key secara langsung (hardcode) di dalam kode Anda:

// ❌ Tidak disarankan: Jangan hardcode
const apiKey = 'zs_xxxxxxxxxxxxxxxxxxxxxxxx';
 
// ✅ Disarankan: Gunakan environment variables
const apiKey = process.env.ZSEND_API_KEY;

2. Terapkan Prinsip Hak Akses Minimum

Buat key terpisah dengan izin yang sesuai untuk setiap aplikasi:

Aplikasi Production: Izin kirim saja + pembatasan domain
Analisis Data: Izin baca saja
Alat Admin: Akses penuh (hanya jika diperlukan)

3. Pantau Penggunaan Key

Lihat statistik penggunaan setiap key di konsol Zeabur Email:

Jumlah permintaan
Jumlah email terkirim
Tingkat error

Segera cabut key jika terdeteksi penggunaan yang tidak wajar.

4. Jangan Berbagi Key

Buat key terpisah untuk setiap aplikasi dan environment (development/production) agar lebih mudah dilacak dan dikelola.

Pemecahan Masalah

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Kemungkinan penyebab:

API key salah atau telah dihapus
Format header permintaan salah (seharusnya Authorization: Bearer <token>)
Key memiliki spasi di awal/akhir atau tidak memiliki prefiks Bearer

403 Forbidden

{
  "error": "permission denied",
  "message": "API key does not have permission to send from this domain"
}

Kemungkinan penyebab:

Izin key tidak mencukupi (misalnya menggunakan key baca saja untuk mengirim email)
Domain pengirim tidak termasuk dalam daftar domain yang diizinkan untuk key tersebut
Domain belum terverifikasi

429 Too Many Requests

{
  "error": "too many requests",
  "message": "Rate limit exceeded"
}

Solusi:

Terapkan mekanisme pembatasan laju permintaan (throttling) dan percobaan ulang (retry)
Pertimbangkan untuk meng-upgrade akun Anda agar mendapatkan batas laju yang lebih tinggi
Gunakan API pengiriman massal untuk mengurangi jumlah permintaan

Manajemen Domain Konfigurasi Webhook