Akun dan ruang kerja
Buat kunci API
Buat kunci akses pribadi dengan kemampuan yang dipilih (agent:operate, agent:publish, agent:engage), batas workspace_ids opsional, dan masa berlaku maksimal 365 hari; rahasia dikembalikan sekali dan tidak dapat dibaca lagi. Agen hanya dapat memberikan kewenangan yang dimilikinya, selama paling lama 30 hari, dan kunci berhenti berlaku saat izin tersebut berakhir. Memerlukan izin Kelola kunci API; PAT tidak dapat menggunakannya.
POST /identity-api/api-keys/createKontrak ditinjau: · sha256:563d2d581da0ad29
Ringkasan
Buat kunci akses pribadi dengan kemampuan yang dipilih (agent:operate, agent:publish, agent:engage), batas workspace_ids opsional, dan masa berlaku maksimal 365 hari; rahasia dikembalikan sekali dan tidak dapat dibaca lagi. Agen hanya dapat memberikan kewenangan yang dimilikinya, selama paling lama 30 hari, dan kunci berhenti berlaku saat izin tersebut berakhir. Memerlukan izin Kelola kunci API; PAT tidak dapat menggunakannya.
Setiap otorisasi terdelegasi dapat memiliki hingga 25 kunci aktif. Permintaan melebihi batas mengembalikan API_KEY_GRANT_KEY_LIMIT.
Respons HTTP berhasil dapat berarti permintaan diterima, bukan selesai. Untuk pekerjaan latar belakang, simpan ID yang dikembalikan dan periksa operasi yang sama sampai selesai. Postingan terjadwal atau diterima baru dipublikasikan setelah platform mengonfirmasi; timeout klien tidak membuktikan hasilnya.
Autentikasi dan izin
Token hanya dapat menggunakan hak pemiliknya. Setiap permintaan memeriksa keanggotaan ruang kerja, kepemilikan sumber daya, ruang kerja terpilih, dan kemampuan yang diberikan. Profil core dan full mengubah alat yang ditampilkan; tidak memberikan akses.
Kolom permintaan
Wajib berarti wajib dalam objek induk dan cabang yang dipilih. Anak wajib tidak membuat induk opsional menjadi wajib. Aturan dan nama kolom di bawah disalin dari kontrak.
| Kolom / cabang | Jenis / wajib | Batasan |
|---|---|---|
$ | objectWajib dalam induk |
|
name | stringWajib dalam induk |
|
lifetime_days | integerOpsional / item | Hari sampai kunci kedaluwarsa (1-365, default 365). Kunci yang dibuat agen terdelegasi tidak pernah berlaku lebih lama dari 30 hari.
|
capabilities | arrayOpsional / item | Tindakan yang boleh dilakukan kunci. Default untuk pengguna yang masuk adalah operate, publish, dan engage. Agen terdelegasi hanya dapat memberikan kewenangan yang dimilikinya (tidak pernah pengelolaan kunci).
|
capabilities[] | stringOpsional / item |
|
workspace_ids | arrayOpsional / item | Batasi kunci pada ruang kerja ini. Hilangkan untuk semua ruang kerja yang dapat diakses pengguna. Kunci terbatas harus menyebutkan ruang kerjanya (workspace_id) pada rute yang biasanya menggunakan ruang kerja aktif, dan tidak dapat memanggil pembacaan seluruh organisasi.
|
workspace_ids[] | stringOpsional / item |
|
scopes | arrayOpsional / item | Alias capabilities yang tidak lagi dianjurkan. Diterapkan persis; daftar kosong diabaikan.
|
scopes[] | stringOpsional / item |
|
idempotency_key | stringOpsional / item | Opsional. Gunakan kunci yang sama untuk mencoba ulang dengan aman. Rahasia ditampilkan sekali: percobaan ulang yang menemukan kunci sudah dibuat menjawab 409 IDEMPOTENT_REPLAY (details.existing_key menyebutkannya), bukan menampilkannya lagi. Cabut kunci itu dan buat yang baru dengan idempotency_key baru.
|
JSON Schema lengkap
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"lifetime_days": {
"default": 365,
"description": "Days until the key expires (1-365, default 365). A key created by a delegated agent never lives longer than 30 days.",
"type": "integer",
"minimum": 1,
"maximum": 365
},
"capabilities": {
"description": "What the key may do. Defaults to operate, publish and engage for a signed-in user. A delegated agent can only grant what its own authorization holds (never key management).",
"minItems": 1,
"maxItems": 3,
"type": "array",
"items": {
"type": "string",
"enum": [
"agent:operate",
"agent:publish",
"agent:engage"
]
}
},
"workspace_ids": {
"description": "Limit the key to these Workspaces. Omit it for every Workspace the user can access. A limited key must name its Workspace (workspace_id) on routes that would otherwise use the active Workspace, and cannot call organization-wide reads.",
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"scopes": {
"description": "Deprecated alias of capabilities. It is honoured exactly; an empty list is ignored.",
"maxItems": 3,
"type": "array",
"items": {
"type": "string",
"enum": [
"agent:operate",
"agent:publish",
"agent:engage"
]
}
},
"idempotency_key": {
"description": "Optional. Reuse the same key to retry safely. The secret is shown once: a retry that finds the key already created answers 409 IDEMPOTENT_REPLAY (details.existing_key names it) instead of showing it again. Revoke that key and create a new one with a new idempotency_key.",
"type": "string",
"minLength": 8,
"maxLength": 160,
"pattern": "^[!-~]+$"
}
},
"required": [
"name"
],
"additionalProperties": false
}Respons dan penyelesaian
Status HTTP berhasil: 200. Saat operasi selesai: synchronous_http_response.
Respons HTTP berhasil dapat berarti permintaan diterima, bukan selesai. Untuk pekerjaan latar belakang, simpan ID yang dikembalikan dan periksa operasi yang sama sampai selesai. Postingan terjadwal atau diterima baru dipublikasikan setelah platform mengonfirmasi; timeout klien tidak membuktikan hasilnya.
Wajib berarti wajib dalam objek induk dan cabang yang dipilih. Anak wajib tidak membuat induk opsional menjadi wajib. Aturan dan nama kolom di bawah disalin dari kontrak.
| Kolom / cabang | Jenis / wajib | Batasan |
|---|---|---|
$ | objectWajib dalam induk | — |
apiKey | objectWajib dalam induk | — |
apiKey.id | stringWajib dalam induk |
|
apiKey.name | stringWajib dalam induk | — |
apiKey.last_4 | stringWajib dalam induk | — |
apiKey.scopes | arrayWajib dalam induk | — |
apiKey.scopes[] | stringOpsional / item | — |
apiKey.created_at | stringWajib dalam induk |
|
apiKey.expires_at | string | nullWajib dalam induk | — |
apiKey.expires_atanyOf 1 | stringWajib dalam induk |
|
apiKey.expires_atanyOf 2 | nullWajib dalam induk | — |
apiKey.last_used_at | string | nullWajib dalam induk | — |
apiKey.last_used_atanyOf 1 | stringWajib dalam induk |
|
apiKey.last_used_atanyOf 2 | nullWajib dalam induk | — |
apiKey.revoked_at | string | nullWajib dalam induk | — |
apiKey.revoked_atanyOf 1 | stringWajib dalam induk |
|
apiKey.revoked_atanyOf 2 | nullWajib dalam induk | — |
apiKey.status | stringWajib dalam induk |
|
apiKey.replaces | object | nullWajib dalam induk | — |
apiKey.replacesanyOf 1 | objectWajib dalam induk | — |
apiKey.replaces.idanyOf 1 | stringWajib dalam induk |
|
apiKey.replaces.nameanyOf 1 | stringWajib dalam induk | — |
apiKey.replaces.last_4anyOf 1 | stringWajib dalam induk | — |
apiKey.replaces.statusanyOf 1 | stringWajib dalam induk |
|
apiKey.replacesanyOf 2 | nullWajib dalam induk | — |
apiKey.replaced_by | arrayWajib dalam induk | — |
apiKey.replaced_by[] | objectOpsional / item | — |
apiKey.replaced_by[].id | stringWajib dalam induk |
|
apiKey.replaced_by[].name | stringWajib dalam induk | — |
apiKey.replaced_by[].last_4 | stringWajib dalam induk | — |
apiKey.replaced_by[].status | stringWajib dalam induk |
|
apiKey.capabilities | arrayOpsional / item | — |
apiKey.capabilities[] | stringOpsional / item |
|
apiKey.workspace_ids | array | nullOpsional / item | — |
apiKey.workspace_idsanyOf 1 | arrayOpsional / item | — |
apiKey.workspace_ids[]anyOf 1 | stringOpsional / item |
|
apiKey.workspace_idsanyOf 2 | nullOpsional / item | — |
apiKey.created_by_delegated_grant_id | string | nullOpsional / item | — |
apiKey.created_by_delegated_grant_idanyOf 1 | stringOpsional / item |
|
apiKey.created_by_delegated_grant_idanyOf 2 | nullOpsional / item | — |
secret | stringWajib dalam induk |
|
JSON Schema lengkap
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"apiKey": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"last_4": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"created_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"active",
"expired",
"revoked"
]
},
"replaces": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"last_4": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"active",
"expired",
"revoked"
]
}
},
"required": [
"id",
"name",
"last_4",
"status"
]
},
{
"type": "null"
}
]
},
"replaced_by": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"last_4": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"active",
"expired",
"revoked"
]
}
},
"required": [
"id",
"name",
"last_4",
"status"
]
}
},
"capabilities": {
"type": "array",
"items": {
"type": "string",
"enum": [
"agent:operate",
"agent:publish",
"agent:engage"
]
}
},
"workspace_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
{
"type": "null"
}
]
},
"created_by_delegated_grant_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"name",
"last_4",
"scopes",
"created_at",
"expires_at",
"last_used_at",
"revoked_at",
"status",
"replaces",
"replaced_by"
]
},
"secret": {
"type": "string",
"minLength": 1
}
},
"required": [
"apiKey",
"secret"
]
}Kesalahan dan percobaan ulang aman
Periksa status HTTP dan isi respons. Kesalahan validasi 400 mungkin berisi ZodError; kesalahan handler menggunakan kolom error, message, dan code. Simpan request_id atau x-request-id untuk diagnosis, tanpa kredensial. Atasi kesalahan akses 401/403 sebelum mencoba lagi, dan ikuti Retry-After untuk 429. Jika penulisan belum pasti atau mengembalikan 5xx, baca hasil yang sudah ada terlebih dahulu. Gunakan kembali kunci idempotensi hanya jika didukung; perilaku percobaan ulang berbeda menurut operasi dan tidak menjamin pengiriman tepat satu kali.
Panduan pemecahan masalahContoh
Contoh ini menggunakan nilai fiktif yang diperiksa terhadap skema. Ganti ID dengan yang diizinkan bagi Anda, media dengan aset siap, dan tanggal dengan waktu publikasi yang dikonfirmasi. Periksa kelayakan akun sebelum mengirim penulisan. Halaman ini tidak mengirim permintaan API.
Atur SOSOAPI_ACCESS_TOKEN di server Anda ke kredensial yang diterima operasi ini, dan jauhkan dari kode browser. Untuk agen, gunakan sosoapi auth login untuk masuk melalui browser dan biarkan CLI memperbarui kredensialnya.
request.json
{
"name": "example"
}cURL
curl --request POST \
"https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/api-keys/create" \
-H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @request.jsonJavaScript
// Server-side JavaScript. Do not print tokens or credential-bearing responses.
const token = process.env.SOSOAPI_ACCESS_TOKEN;
if (!token) throw new Error("Set an accepted credential for this operation");
const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/identity-api/api-keys/create", {
method: "POST",
headers: { "Content-Type": "application/json", Authorization: "Bearer " + token },
body: JSON.stringify({
"name": "example"
})
});
const result = await response.json();
// Check response.ok, the operation-specific body and completion state before continuing.CLI
npx sosoapi api post /identity-api/api-keys/create < request.jsonContoh respons sintetis
{
"apiKey": {
"id": "11111111-1111-4111-8111-111111111111",
"name": "example",
"last_4": "example",
"scopes": [],
"created_at": "2099-01-15T09:00:00Z",
"expires_at": null,
"last_used_at": null,
"revoked_at": null,
"status": "active",
"replaces": null,
"replaced_by": []
},
"secret": "example"
}