ต่อระบบ
Management API และ service account
เรียก API ในฐานะผู้ใช้ที่ล็อกอินหรือบริการหลังบ้าน พร้อม scope และรูปแบบข้อผิดพลาด
ทุกอย่างที่คอนโซลทำได้ Management API ทำได้: อ่านผังองค์กร จัดการสมาชิกและ role ลงทะเบียน webhook ทุกโทเค็นจำกัดอยู่ที่ tenant เดียวและตรวจสิทธิ์ด้วย permission ไม่ว่าผู้เรียกจะเป็นคนที่ล็อกอินหรือบริการหลังบ้าน
ผู้เรียกสองแบบ
| ผู้เรียก | โทเค็น | ตรวจสิทธิ์ด้วย |
|---|---|---|
| คนที่ล็อกอิน (แอปทำแทนผู้ใช้) | access token ของผู้ใช้จาก OIDC flow | สิทธิ์ที่มีผลของสมาชิก — สิทธิ์ในตัวอย่าง directory:read, access:write, tenant:admin |
| บริการหลังบ้าน | service token จาก client_credentials ของ service account | scope ที่ให้ service account ไว้ |
Service account
ผู้ดูแล tenant สร้าง service account ที่ ตั้งค่า → Service accounts แต่ละตัวเป็นของแอปที่ติดตั้ง และได้ scope บางส่วน client secret แสดงครั้งเดียวและหมุนได้
| Scope | ให้ทำอะไร |
|---|---|
directory.read | อ่านสมาชิก หน่วยงาน ตำแหน่ง กลุ่ม attribute; resolve |
directory.write | สร้าง/แก้สิ่งข้างต้น เชิญและนำเข้าสมาชิก |
access.read | อ่าน role, binding, แอปที่ติดตั้ง, explain |
access.write | จัดการ role และ binding |
tenant.admin | ทุกอย่างที่ผู้ดูแล tenant ทำได้ (นโยบาย webhook session…) |
application.manifest | sync manifest ของแอปที่เป็นเจ้าของ service account |
curl -X POST https://auth.suphark.com/api/auth/oauth2/token \
-d grant_type=client_credentials \
-d client_id=$SA_CLIENT_ID -d client_secret=$SA_CLIENT_SECRET \
-d "scope=directory.read access.read"
# → { "access_token": "…", "token_type": "Bearer", "expires_in": 3600 }เรียก API
curl https://auth.suphark.com/api/v1/members?orgUnitId=ou_…&includeDescendants=true \
-H "Authorization: Bearer $TOKEN"curl -X POST https://auth.suphark.com/api/v1/directory/resolve \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "positionCode": "DIR", "withinOrgPathOf": "68dc9b7a…", "nearestOnly": true }'
# → { "matches": [ { "membershipId": "…", "name": "…", "email": "…",
# "orgUnit": { "path": "/acme" }, "position": { "code": "DIR", "level": 1 },
# "via": "PRIMARY", "validTo": null } ] }tenant คือ tenant ที่ผูกกับโทเค็นเสมอ — ไม่มีพารามิเตอร์ tenant และโทเค็นของ tenant หนึ่งอ่านอีก tenant ไม่ได้
Resource
| Path | อะไร |
|---|---|
/api/v1/members | รายการ เชิญ นำเข้า/ส่งออก CSV; /{id}/role, /suspend, /reactivate, /leave, /permissions (+/explain) |
/api/v1/org-units · /positions · /groups · /attributes · /assignments | ผังองค์กรและใครนั่งตรงไหน |
/api/v1/directory/resolve | หาผู้ถือตำแหน่งเทียบกับหน่วยงานหรือสมาชิก |
/api/v1/roles · /installations · /applications | role และ binding, แอปที่ติดตั้ง, manifest |
/api/v1/webhooks · /service-accounts · /scim-tokens | การเชื่อมต่อ |
/api/v1/policies · /connections · /sessions · /audit-events | ความปลอดภัย |
/api/v1/tenant · /tenant/usage · /me | การตั้งค่า tenant และบริบทของผู้เรียกเอง |
ข้อผิดพลาด
ข้อผิดพลาดเป็น RFC 9457 application/problem+json พร้อม code ที่เครื่องอ่านได้และคงที่ — ใช้ code ในโค้ด; detail เป็นข้อความสำหรับคน ตามภาษาของ request (header Accept-Language: en หรือ th; ไม่ส่ง = ไทย):
{
"type": "https://auth.suphark.com/errors/permission-denied",
"title": "Permission denied",
"status": 403,
"code": "PERMISSION_DENIED",
"detail": "requires access:write"
}VALIDATION_FAILED(400) — body หรือ query ไม่ผ่าน schema;issues[]บอกฟิลด์UNAUTHENTICATED(401) — ไม่มีหรือโทเค็นไม่ถูกต้องPERMISSION_DENIED(403),NOT_FOUND(404),CONFLICT(409) — ข้อมูลของ tenant อื่นตอบ 404 เสมอ ไม่ใช่ 403