Admin API

Admin — Override Batas Undangan Tim

Copy page

Halaman ini menjelaskan cara tim operasional memanggil endpoint admin PATCH /api/admin/team-invite-limit untuk mengatur atau menghapus batas undangan tim (seat) per akun.

Apa yang dilakukan override ini

Setiap tim punya batas jumlah member yang bisa diundang (seat limit). Secara default batas ini diturunkan dari tier subscription milik owner tim.

Endpoint ini menyetel field maxInvitedTeamMembers pada user (owner tim). Nilai override ini lebih diprioritaskan dibanding batas tier saat batas efektif dihitung di resolveTeamInviteLimit:

• Jika maxInvitedTeamMembers berisi angka → angka itulah yang dipakai sebagai batas.
• Jika maxInvitedTeamMembers bernilai null → override dianggap kosong dan batas kembali mengikuti tier subscription.

Secara ringkas, logikanya adalah maxInvitedTeamMembers ?? batasDariTier.

Autentikasi

Endpoint ini tidak memakai sesi login. Autentikasi memakai shared secret lewat header Authorization:

Code
Authorization: Bearer <ADMIN_API_TOKEN>

• <ADMIN_API_TOKEN> diambil dari environment variable ADMIN_API_TOKEN di server.
• Header harus memakai skema Bearer diikuti token yang sama persis dengan ADMIN_API_TOKEN.

Catatan operasional: jika ADMIN_API_TOKEN tidak diset di server, endpoint akan gagal tertutup (fail closed) dan mengembalikan status 500, bukan membuka akses.

Request body (JSON)

Method: PATCH — Content-Type: application/json.

Body divalidasi secara ketat (strict), jadi field yang tidak dikenal akan ditolak. Field yang diterima:

Field	Tipe	Wajib	Keterangan
email	string	Ya	Email owner/user tim target. Divalidasi sebagai format email, maksimal 255 karakter, otomatis di-trim dan diubah ke huruf kecil (toLowerCase).
maxInvitedTeamMembers	integer atau null	Ya	Angka integer antara 1 dan 10000 untuk menyetel override, atau null untuk menghapus override (kembali ke batas tier).

Semantik set vs clear

• Set angka: kirim integer 1–10000. Nilai ini menjadi batas seat efektif untuk tim milik user tersebut, mengalahkan batas tier.
• Clear dengan null: kirim null untuk menghapus override. Setelah itu batas seat kembali mengikuti tier subscription owner.

Batasan (validation bounds) yang benar-benar dijalankan

• email: harus format email valid, panjang maksimal 255 karakter.
• maxInvitedTeamMembers: harus berupa integer (bilangan bulat), minimal 1, maksimal 10000, atau null. Nilai 0, angka negatif, angka desimal, atau di atas 10000 akan ditolak sebagai error validasi.

Response

Sukses — 200 OK

Code
{
  "success": true,
  "data": {
    "email": "owner@contoh.com",
    "maxInvitedTeamMembers": 5
  }
}

Saat override dihapus dengan null, data.maxInvitedTeamMembers bernilai null.

Error

Status	error.code	Kapan terjadi
401	UNAUTHORIZED	Header Authorization tidak ada, formatnya salah (bukan Bearer <token>), atau token tidak cocok dengan ADMIN_API_TOKEN.
400	VALIDATION_ERROR	Body bukan JSON valid (pesan Invalid JSON), atau gagal validasi schema seperti email tidak valid / maxInvitedTeamMembers di luar rentang (pesan Invalid Request, disertai details).
404	RESOURCE_NOT_FOUND	Tidak ada user dengan email tersebut.
500	SERVER_MISCONFIGURED	ADMIN_API_TOKEN tidak diset di server.
500	INTERNAL_ERROR	Terjadi error tak terduga di server.

Contoh body error:

Code
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "User not found"
  }
}

Contoh curl

Menyetel override menjadi 5 seat untuk sebuah user:

Code
curl -X PATCH "https://<host>/api/admin/team-invite-limit" \
  -H "Authorization: Bearer $ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@contoh.com",
    "maxInvitedTeamMembers": 5
  }'

Menghapus override (kembali ke batas tier):

Code
curl -X PATCH "https://<host>/api/admin/team-invite-limit" \
  -H "Authorization: Bearer $ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "owner@contoh.com",
    "maxInvitedTeamMembers": null
  }'

Catatan Postman: buat request baru dengan method PATCH ke URL di atas, tab Authorization pilih tipe Bearer Token lalu isi dengan ADMIN_API_TOKEN, dan pada tab Body pilih raw → JSON dengan isi seperti contoh di atas.