External System Integration

Bahasa Indonesia

English

Bahasa Indonesia

English

Appearance

Getting Started ​

Halaman ini adalah versi Indonesia untuk developer pemula.

1) Pahami dua mode auth ​

Service auth ​

  • Untuk integrasi machine-to-machine.
  • Format auth: CredentialType=service, CredentialId=<service-id>
  • Signed headers: x-date;x-request-id;x-client-type

User auth ​

  • Untuk request user tenant.
  • Format auth: CredentialType=user, CredentialId=<user-email>
  • Wajib X-Tenant-Id.
  • Signed headers: x-date;x-tenant-id;x-request-id;x-client-type

2) Header wajib ​

  • Authorization
  • X-Date (ISO-8601 UTC)
  • X-Request-Id (UUID, selalu baru)
  • X-Client-Type
  • X-Tenant-Id (khusus user auth)

3) Alur signature ​

  1. Bentuk canonical request (format standar request).
  2. Hash canonical request dengan SHA-256.
  3. Bentuk string to sign:
text
HMAC-SHA256
<X-Date>
<hash-canonical-request>
  1. Hitung HMAC-SHA256 dengan secret key.

4) TypeScript example (ready to use) ​

ts
import { createHash, createHmac, randomUUID } from "node:crypto";

type CredentialType = "service" | "user";

function signedHeaders(type: CredentialType): string[] {
  return type === "user"
    ? ["x-date", "x-tenant-id", "x-request-id", "x-client-type"]
    : ["x-date", "x-request-id", "x-client-type"];
}

const date = new Date().toISOString();
const requestId = randomUUID();

Untuk implementasi penuh, lihat:

5) Checklist debug ​

  • SignedHeaders urutannya harus sama persis dengan server.
  • Canonical headers harus diakhiri newline \n.
  • Untuk GET/DELETE, body hash dari string kosong "".
  • Retry harus pakai request ID baru (jangan reuse).

6) Error paling umum ​

  • 401 Invalid Authorization format
  • 401 Missing required headers
  • 401 Signature expired
  • 401 Invalid signature
  • 401 Replay request detected

Next ​