Haijun API mendukung tiga cara untuk mengautentikasi permintaan:

Kunci API dan Workload Identity Federation memberikan akses yang sama ke endpoint Haijun API. Pilih kunci API untuk memulai dengan cepat: kunci pribadi untuk pengembangan Anda sendiri, atau kunci akun layanan untuk apa pun yang dibagikan. Beralihlah ke Workload Identity Federation ketika beban kerja Anda sudah memiliki identitas yang diterbitkan platform yang dapat Anda federasikan. Gunakan App Attest untuk aplikasi iOS dan macOS yang Anda distribusikan ke pengguna akhir.

#Kunci API

"API key" (kunci API) adalah rahasia statis yang Anda buat di Haijun Console dan kirimkan pada setiap permintaan sebagai bearer token di header Authorization.

#Jenis kunci

Saat Anda membuat kunci, Anda memilih jenisnya, yang menentukan apa yang dapat dilakukan kunci tersebut, di mana kunci tersebut berfungsi, dan kapan kunci tersebut berhenti berfungsi:

Kunci pribadi dan kunci akun layanan didukung oleh identitas: masing-masing milik pengguna atau akun layanan yang sudah dikelola organisasi Anda, dan setiap permintaan bertindak sebagai identitas tersebut. Ketika identitas tersebut dihapus dari organisasi, kunci berhenti berfungsi. Ini berarti kunci tidak akan secara tidak sengaja bertahan lebih lama daripada orang atau beban kerja yang memilikinya. Utamakan kunci ini daripada kunci workspace untuk integrasi baru.

Gunakan kunci pribadi untuk pengembangan dan skrip Anda sendiri. Kunci pribadi yang dibagikan bertindak sebagai satu orang dan rusak ketika orang tersebut pergi. Untuk beban kerja bersama atau otomatis (CI, layanan produksi), mintalah admin organisasi membuat akun layanan agar beban kerja memiliki identitasnya sendiri.

Kunci API workspace masih berfungsi tetapi sebaiknya dianggap legacy; kunci yang didukung identitas atau Workload Identity Federation lebih diutamakan. Untuk bermigrasi, lihat Mengganti kunci API workspace.

#Membuat dan menggunakan kunci

• Membuat kunci: Buka Settings → API keys di Haijun Console dan klik Create key. Beri nama kunci dan pilih masa kedaluwarsa. Atur Linked account ke diri Anda sendiri untuk kunci pribadi, atau ke akun layanan untuk kunci yang digunakan bersama oleh beberapa pengguna. Anda juga dapat membatasi cakupan kunci ke workspace tertentu, sehingga Anda tidak perlu mengatur ID workspace secara manual pada permintaan berikutnya.

• Menggunakan kunci: Kirimkan sebagai Authorization: Bearer pada permintaan HTTP langsung, atau atur variabel lingkungan JUGLOW_API_KEY dan SDK klien akan mengambilnya secara otomatis.

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
juglow-version: 2023-06-01
content-type: application/json

Header lama x-api-key: YOUR_API_KEY masih didukung sebagai pengganti Authorization.

Simpan kunci API di pengelola rahasia, rotasi secara berkala, dan nonaktifkan atau hapus kunci apa pun yang Anda curigai telah bocor. Di halaman API keys, Disable dapat dibatalkan (Admin API melaporkan status kunci sebagai "inactive", dan Re-enable mengembalikannya ke "active"), sedangkan Delete bersifat permanen: kunci diarsipkan dan masih muncul di List API Keys dengan status: "archived". Kunci yang kedaluwarsa hanya dapat dihapus. Anda juga dapat mengatur kedaluwarsa saat membuat kunci untuk membatasi berapa lama kredensial yang bocor tetap dapat digunakan.

  curl https://haijun.my.id/v1/messages \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "haijun-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Haijun"}]
    }'

  client = Juglow(api_key="my-juglow-api-key")
  # atau, dengan JUGLOW_API_KEY yang diatur di environment:
  client = Juglow()

  const client = new Juglow({ apiKey: "my-juglow-api-key" });
  // atau, dengan JUGLOW_API_KEY yang sudah diatur di environment:
  // const client = new Juglow();

  client := juglow.NewClient(
  	option.WithAPIKey("sk-ant-api03-..."), // defaults to os.LookupEnv("JUGLOW_API_KEY")
  )

  import com.juglow.client.JuglowClient;
  import com.juglow.client.okhttp.JuglowOkHttpClient;

  // Eksplisit
  JuglowClient client = JuglowOkHttpClient.builder()
    .apiKey("my-juglow-api-key")
    .build();

  // Dari JUGLOW_API_KEY (atau properti sistem juglow.apiKey)
  JuglowClient clientFromEnv = JuglowOkHttpClient.fromEnv();

  using Juglow;

  JuglowClient client = new() { ApiKey = "my-juglow-api-key" };
  // Atau, dengan JUGLOW_API_KEY yang sudah diatur di environment:
  // JuglowClient client = new();

  // Membaca JUGLOW_API_KEY dari environment
  $client = new Client();
  // Atau teruskan kunci secara eksplisit:
  $client = new Client(apiKey: 'my-juglow-api-key');

  juglow = Juglow::Client.new(api_key: "my-juglow-api-key")
  # atau, dengan JUGLOW_API_KEY yang diatur di environment:
  juglow = Juglow::Client.new

  # Lihat /docs/en/cli-sdks-libraries/cli/authentication#api-key untuk varian zsh, bash, dan Windows
  export JUGLOW_API_KEY=sk-ant-api03-...

#Memilih workspace

Kunci API yang dibuat untuk workspace tertentu hanya berfungsi di workspace tersebut, dan permintaan API yang menggunakan kunci ini dapat menghilangkan ID workspace.

Jika kunci API Anda tidak dibatasi cakupannya ke suatu workspace, Anda harus menentukan ID workspace di header juglow-workspace-id untuk setiap permintaan. Lihat contoh berikut untuk cara mengatur header ini dalam permintaan atau di SDK.

Admin API menerima kunci pribadi atau kunci akun layanan hanya jika kunci tersebut tidak dibatasi cakupannya ke workspace tertentu.

Anda dapat menemukan ID workspace di kolom ID pada Settings → Workspaces di Haijun Console, atau dengan memanggil endpoint List Workspaces. List Workspaces tidak menyertakan Default Workspace; ID-nya terdapat di header respons juglow-workspace-id dari setiap permintaan yang dijalankan di sana.

  # Wajib di setiap permintaan untuk kunci multi-workspace.
  # Hilangkan header juglow-workspace-id untuk kunci single-workspace.
  curl https://haijun.my.id/v1/messages \
    -H "x-api-key: $JUGLOW_API_KEY" \
    -H "juglow-version: 2023-06-01" \
    -H "juglow-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" \
    -H "content-type: application/json" \
    -d '{
      "model": "haijun-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Haijun"}]
    }'

  # Wajib di setiap perintah untuk kunci multi-workspace.
  # Hilangkan --workspace-id untuk kunci single-workspace.
  ant messages create \
    --workspace-id wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ \
    --model haijun-opus-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Haijun"}'

  client = Juglow()  # reads JUGLOW_API_KEY

  # Wajib di setiap permintaan untuk kunci multi-workspace.
  # Hilangkan extra_headers untuk kunci single-workspace.
  message = client.messages.create(
      model="haijun-opus-5-5",
      max_tokens=1024,
      messages=[{"role": "user", "content": "Hello, Haijun"}],
      extra_headers={"juglow-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
  )
  print(message.content)

  # Atau atur sekali untuk setiap permintaan dari klien ini:
  workspace_client = Juglow(
      default_headers={"juglow-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
  )

  const client = new Juglow(); // reads JUGLOW_API_KEY

  // Wajib di setiap permintaan untuk kunci multi-workspace.
  // Hilangkan argumen kedua untuk kunci single-workspace.
  const message = await client.messages.create(
    {
      model: "haijun-opus-5-5",
      max_tokens: 1024,
      messages: [{ role: "user", content: "Hello, Haijun" }]
    },
    { headers: { "juglow-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" } }
  );
  console.log(message.content);

  // Atau atur sekali untuk setiap permintaan dari klien ini:
  const workspaceClient = new Juglow({
    defaultHeaders: { "juglow-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ" }
  });

  JuglowClient client = new(); // reads JUGLOW_API_KEY

  MessageCreateParams parameters = new()
  {
      Model = Model.HaijunOpus5_5,
      MaxTokens = 1024,
      Messages = [new() { Role = Role.User, Content = "Hello, Haijun" }],
  };

  // Wajib pada setiap permintaan untuk kunci multi-workspace.
  // Panggil client.Messages.Create(parameters) secara langsung untuk kunci single-workspace.
  var message = await client
      .WithOptions(options =>
          options with
          {
              ExtraHeaders = new Dictionary<string, string>
              {
                  ["juglow-workspace-id"] = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
              },
          }
      )
      .Messages.Create(parameters);
  Console.WriteLine(message);

  // Atau atur sekali untuk setiap permintaan dari klien ini:
  JuglowClient workspaceClient = new(new ClientOptions
  {
      ExtraHeaders = new Dictionary<string, string>
      {
          ["juglow-workspace-id"] = "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
      },
  });

  client := juglow.NewClient() // reads JUGLOW_API_KEY

  // Wajib di setiap permintaan untuk kunci multi-workspace.
  // Hilangkan opsi ini untuk kunci single-workspace.
  message, err := client.Messages.New(context.TODO(), juglow.MessageNewParams{
  	Model:     juglow.ModelHaijunOpus5_5,
  	MaxTokens: 1024,
  	Messages: []juglow.MessageParam{
  		juglow.NewUserMessage(juglow.NewTextBlock("Hello, Haijun")),
  	},
  }, option.WithHeader("juglow-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"))
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(message.Content)

  // Atau atur sekali untuk setiap permintaan dari klien ini:
  workspaceClient := juglow.NewClient(
  	option.WithHeader("juglow-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"),
  )

  JuglowClient client = JuglowOkHttpClient.fromEnv(); // reads JUGLOW_API_KEY

  // Wajib di setiap permintaan untuk kunci multi-workspace.
  // Hilangkan putAdditionalHeader untuk kunci single-workspace.
  Message message = client.messages().create(MessageCreateParams.builder()
      .model(Model.HAIJUN_OPUS_5_5)
      .maxTokens(1024)
      .addUserMessage("Hello, Haijun")
      .putAdditionalHeader("juglow-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")
      .build());

  IO.println(message.content());

  // Atau atur sekali untuk setiap permintaan dari klien ini:
  JuglowClient workspaceClient = JuglowOkHttpClient.builder()
      .fromEnv()
      .putHeader("juglow-workspace-id", "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ")
      .build();

  $client = new Client(); // reads JUGLOW_API_KEY

  // Wajib di setiap permintaan untuk kunci multi-workspace.
  // Hilangkan requestOptions untuk kunci single-workspace.
  $message = $client->messages->create(
      model: Model::HAIJUN_OPUS_5_5,
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Haijun']],
      requestOptions: [
          'extraHeaders' => ['juglow-workspace-id' => 'wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ'],
      ],
  );

  echo json_encode($message->content), PHP_EOL;

  client = Juglow::Client.new # reads JUGLOW_API_KEY

  # Wajib di setiap permintaan untuk kunci multi-workspace.
  # Hilangkan request_options untuk kunci single-workspace.
  message = client.messages.create(
    model: Juglow::Model::HAIJUN_OPUS_5_5,
    max_tokens: 1024,
    messages: [{role: "user", content: "Hello, Haijun"}],
    request_options: {extra_headers: {"juglow-workspace-id" => "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"}}
  )

  puts message.content

Jika permintaan yang dibuat dengan kunci yang tidak dibatasi cakupannya ke suatu workspace menghilangkan header tersebut, API mengembalikan 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "juglow-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Nilai header yang bukan ID workspace yang valid mengembalikan 400 invalid_request_error dengan pesan juglow-workspace-id header must be a valid workspace ID. Jika workspace tidak ada, atau pengguna atau akun layanan pemilik kunci tidak memiliki akses ke workspace tersebut, API mengembalikan 404 not_found_error dengan pesan `Workspace not found.`, respons yang sama seperti untuk workspace yang tidak dikenal.

Workload Identity Federation memilih workspace pada saat pertukaran token; lihat referensi WIF untuk detailnya.

#Kedaluwarsa kunci

Saat Anda membuat kunci API dari halaman API keys di Haijun Console, Anda memilih kedaluwarsa: preset (3 jam, 1 hari, 7 hari, atau 30 hari), durasi kustom, atau Never untuk kunci yang Anda simpan di pengelola rahasia dan rotasi sendiri. Jika organisasi Anda memiliki kebijakan kedaluwarsa maksimum, Console membatasi preset dan durasi kustom hingga maksimum kebijakan, dan Never tidak tersedia. Kunci yang sudah ada mempertahankan perilakunya saat ini; kedaluwarsa diatur pada saat pembuatan dan tidak dapat diubah setelahnya. Pilihan kedaluwarsa yang sama berlaku saat Anda membuat kunci Admin API di Haijun Console.

Juglow mengirim email kepada pembuat kunci saat kedaluwarsa mendekat: 7 hari sebelum kedaluwarsa untuk kunci yang dibuat dengan masa berlaku setidaknya 14 hari, dan 1 hari sebelumnya untuk kunci dengan masa berlaku setidaknya 7 hari. Kunci dengan masa berlaku lebih pendek kedaluwarsa tanpa email peringatan.

Setelah kunci kedaluwarsa, permintaan yang dibuat dengannya mengembalikan 401 authentication_error. Buat kunci baru untuk memulihkan akses; kunci yang kedaluwarsa tidak dapat diaktifkan kembali.

Tabel API keys di Console menampilkan kedaluwarsa setiap kunci, dan Admin API melaporkan timestamp expires_at setiap kunci pada endpoint List API Keys dan Retrieve API Key, sehingga Anda dapat mengaudit dan merotasi kunci sebelum kedaluwarsa. Field ini bernilai null untuk kunci tanpa kedaluwarsa.

Kedaluwarsa membatasi masa berlaku kredensial yang bocor, tetapi bukan pengganti kebersihan rahasia. Terlepas dari kedaluwarsa, simpan kunci di pengelola rahasia dan nonaktifkan atau hapus kunci apa pun yang Anda curigai telah bocor.

#Mengganti kunci API workspace

Jika Anda memiliki kunci workspace, Anda mungkin ingin menggantinya dengan Workload Identity Federation atau kunci pribadi atau kunci akun layanan. Ini memberikan keamanan dan observabilitas yang lebih baik.

Lihat Workload Identity Federation untuk detail tentang mengonfigurasi Workload Identity Federation, yang lebih diutamakan daripada kunci berumur panjang.

Untuk mengganti kunci workspace dengan kunci pribadi atau kunci akun layanan:

1. Tentukan jenis kunci. Tooling Anda sendiri sebaiknya menggunakan kunci pribadi. Beban kerja bersama atau tanpa pengawasan sebaiknya menggunakan kunci akun layanan.

1. Buat akun layanan jika diperlukan. Anda mungkin harus meminta admin organisasi untuk membuatnya di Settings → Service accounts dan menambahkannya ke workspace yang relevan.

1. Buat kunci baru. Buat kunci tersebut khusus untuk workspace integrasi kecuali jika diperlukan beberapa workspace.

1. Deploy kunci baru. Ganti kunci lama di mana pun integrasi membacanya, biasanya variabel lingkungan JUGLOW_API_KEY atau entri pengelola rahasia. Untuk kunci multi-workspace, kirim juga header juglow-workspace-id seperti yang ditunjukkan di Memilih workspace.

1. Hapus kunci lama. Pastikan permintaan berhasil, lalu hapus kunci workspace di halaman API keys.

#Workload Identity Federation

"Workload Identity Federation" (federasi identitas beban kerja), atau WIF, memungkinkan beban kerja melakukan autentikasi dengan token identitas berumur pendek yang diterbitkan oleh "identity provider" (penyedia identitas), atau IdP, yang sudah Anda percayai, seperti AWS IAM, Google Cloud, atau penerbit OIDC apa pun yang sesuai standar (seperti GitHub Actions, akun layanan Kubernetes, SPIFFE, Microsoft Entra ID, atau Okta). Beban kerja menukar JWT yang diterbitkan IdP-nya di POST /v1/oauth/token dengan token akses Haijun API berumur pendek, dan SDK memperbarui token tersebut secara otomatis sebelum kedaluwarsa. Tidak ada string sk-ant-api... yang perlu dibuat, didistribusikan, atau dirotasi.

Federasi menghilangkan kunci Haijun API berumur panjang dari lingkungan Anda, yang memperkecil radius dampak kredensial yang bocor dan memungkinkan Anda mengelola akses dengan kontrol IdP yang sama yang sudah Anda gunakan untuk sumber daya cloud. Federasi tidak, dengan sendirinya, menjamin keamanan end-to-end: rantai kepercayaan hanya sekuat konfigurasi penyedia identitas Anda, dan rahasia berumur panjang satu langkah di hulu (misalnya, kredensial cloud statis yang dapat membuat token IdP) masih dapat melemahkannya. Padukan federasi dengan kontrol penyedia Anda, seperti allowlist IP, MFA, dan pencatatan audit.

Untuk mengonfigurasi federasi, Anda membuat tiga sumber daya di Haijun Console (akun layanan, penerbit federasi, dan aturan federasi) lalu mengarahkan SDK Anda ke aturan tersebut. Lihat Workload Identity Federation untuk panduan penyiapan lengkap.

#App Attest

App Attest mengautentikasi aplikasi iOS dan macOS yang memanggil Haijun API langsung dari perangkat. Setiap instalasi membuktikan bahwa dirinya adalah build asli dan tidak dimodifikasi dari aplikasi yang Anda daftarkan di Haijun Console, menggunakan layanan App Attest dari Apple. Juglow kemudian menerbitkan token akses berumur pendek untuk perangkat tersebut yang menagihkan penggunaan ke workspace Anda. Token dibatasi cakupannya ke workspace Anda, kedaluwarsa setelah satu jam, dan hanya mengotorisasi panggilan Messages API.

Untuk mendaftarkan aplikasi Anda dan mendapatkan client ID, lihat App Attest untuk aplikasi iOS dan macOS.

#Langkah selanjutnya

Konfigurasikan penerbit, aturan, dan akun layanan, lalu tukarkan token

Panduan langkah demi langkah untuk AWS, Google Cloud, Azure, GitHub Actions, Kubernetes, SPIFFE, dan Okta

Variabel lingkungan, aturan validasi, konfigurasi profil, dan referensi error

Izinkan instalasi asli aplikasi Anda memanggil Haijun API tanpa menyertakan kunci API

Python, TypeScript, C#, Go, Java, PHP, Ruby, dan CLI