Konten und Workspaces
API-Schlüssel erstellen
Erstelle einen persönlichen Zugriffsschlüssel mit gewählten Funktionen (agent:operate, agent:publish, agent:engage), optionaler workspace_ids-Grenze und bis 365 Tagen Laufzeit; das Geheimnis wird einmal zurückgegeben und ist danach nicht lesbar. Ein Agent kann nur eigene Befugnisse für höchstens 30 Tage weitergeben; endet die Autorisierung, stoppt auch der Schlüssel. Erfordert „API-Schlüssel verwalten“; ein PAT kann dies nicht nutzen.
POST /identity-api/api-keys/createVertrag geprüft: · sha256:563d2d581da0ad29
Überblick
Erstelle einen persönlichen Zugriffsschlüssel mit gewählten Funktionen (agent:operate, agent:publish, agent:engage), optionaler workspace_ids-Grenze und bis 365 Tagen Laufzeit; das Geheimnis wird einmal zurückgegeben und ist danach nicht lesbar. Ein Agent kann nur eigene Befugnisse für höchstens 30 Tage weitergeben; endet die Autorisierung, stoppt auch der Schlüssel. Erfordert „API-Schlüssel verwalten“; ein PAT kann dies nicht nutzen.
Jede delegierte Autorisierung darf bis 25 aktive Schlüssel haben. Darüber liefern Anfragen API_KEY_GRANT_KEY_LIMIT.
Eine erfolgreiche HTTP-Antwort kann Annahme statt Abschluss bedeuten. Speichere bei Hintergrundarbeit die ID und prüfe dieselbe Operation bis zum Abschluss. Geplante oder angenommene Beiträge gelten erst nach Plattformbestätigung als veröffentlicht; ein Client-Timeout klärt das Ergebnis nicht.
Authentifizierung und Berechtigungen
Ein Token nutzt nur Eigentümerrechte. Jede Anfrage prüft Workspace-Mitgliedschaft, Ressourceneigentum, gewählte Workspaces und Funktionen. core und full ändern sichtbare Tools; sie erteilen keinen Zugriff.
Anfragefelder
Erforderlich bedeutet innerhalb des übergeordneten Objekts und gewählten Zweigs erforderlich. Ein erforderliches Kind macht kein optionales Elternobjekt erforderlich. Regeln und Feldnamen unten stammen aus dem Vertrag.
| Feld / Variante | Typ / erforderlich | Einschränkungen |
|---|---|---|
$ | objectIm Elternobjekt erforderlich |
|
name | stringIm Elternobjekt erforderlich |
|
lifetime_days | integerOptional / Element | Tage bis zum Schlüsselablauf (1-365, Standard 365). Ein von einem delegierten Agenten erstellter Schlüssel gilt nie länger als 30 Tage.
|
capabilities | arrayOptional / Element | Erlaubte Schlüsselaktionen. Standard für angemeldete Nutzer: operate, publish und engage. Ein delegierter Agent kann nur eigene Berechtigungen weitergeben (niemals Schlüsselverwaltung).
|
capabilities[] | stringOptional / Element |
|
workspace_ids | arrayOptional / Element | Begrenze den Schlüssel auf diese Workspaces. Weglassen für alle zugänglichen Workspaces. Ein begrenzter Schlüssel muss bei Routen mit sonst aktivem Workspace seinen Workspace (workspace_id) nennen und darf keine organisationsweiten Lesezugriffe ausführen.
|
workspace_ids[] | stringOptional / Element |
|
scopes | arrayOptional / Element | Veralteter Alias von capabilities. Wird exakt beachtet; eine leere Liste wird ignoriert.
|
scopes[] | stringOptional / Element |
|
idempotency_key | stringOptional / Element | Optional. Nutze denselben Schlüssel für sichere Wiederholungen. Das Geheimnis wird einmal angezeigt: Findet eine Wiederholung einen bereits erstellten Schlüssel, antwortet sie mit 409 IDEMPOTENT_REPLAY (details.existing_key benennt ihn), statt es erneut zu zeigen. Widerrufe den Schlüssel und erstelle mit neuem idempotency_key einen neuen.
|
Vollständiges JSON Schema
{
"$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
}Antwort und Abschluss
HTTP-Erfolgsstatus: 200. Wenn die Operation abgeschlossen ist: synchronous_http_response.
Eine erfolgreiche HTTP-Antwort kann Annahme statt Abschluss bedeuten. Speichere bei Hintergrundarbeit die ID und prüfe dieselbe Operation bis zum Abschluss. Geplante oder angenommene Beiträge gelten erst nach Plattformbestätigung als veröffentlicht; ein Client-Timeout klärt das Ergebnis nicht.
Erforderlich bedeutet innerhalb des übergeordneten Objekts und gewählten Zweigs erforderlich. Ein erforderliches Kind macht kein optionales Elternobjekt erforderlich. Regeln und Feldnamen unten stammen aus dem Vertrag.
| Feld / Variante | Typ / erforderlich | Einschränkungen |
|---|---|---|
$ | objectIm Elternobjekt erforderlich | — |
apiKey | objectIm Elternobjekt erforderlich | — |
apiKey.id | stringIm Elternobjekt erforderlich |
|
apiKey.name | stringIm Elternobjekt erforderlich | — |
apiKey.last_4 | stringIm Elternobjekt erforderlich | — |
apiKey.scopes | arrayIm Elternobjekt erforderlich | — |
apiKey.scopes[] | stringOptional / Element | — |
apiKey.created_at | stringIm Elternobjekt erforderlich |
|
apiKey.expires_at | string | nullIm Elternobjekt erforderlich | — |
apiKey.expires_atanyOf 1 | stringIm Elternobjekt erforderlich |
|
apiKey.expires_atanyOf 2 | nullIm Elternobjekt erforderlich | — |
apiKey.last_used_at | string | nullIm Elternobjekt erforderlich | — |
apiKey.last_used_atanyOf 1 | stringIm Elternobjekt erforderlich |
|
apiKey.last_used_atanyOf 2 | nullIm Elternobjekt erforderlich | — |
apiKey.revoked_at | string | nullIm Elternobjekt erforderlich | — |
apiKey.revoked_atanyOf 1 | stringIm Elternobjekt erforderlich |
|
apiKey.revoked_atanyOf 2 | nullIm Elternobjekt erforderlich | — |
apiKey.status | stringIm Elternobjekt erforderlich |
|
apiKey.replaces | object | nullIm Elternobjekt erforderlich | — |
apiKey.replacesanyOf 1 | objectIm Elternobjekt erforderlich | — |
apiKey.replaces.idanyOf 1 | stringIm Elternobjekt erforderlich |
|
apiKey.replaces.nameanyOf 1 | stringIm Elternobjekt erforderlich | — |
apiKey.replaces.last_4anyOf 1 | stringIm Elternobjekt erforderlich | — |
apiKey.replaces.statusanyOf 1 | stringIm Elternobjekt erforderlich |
|
apiKey.replacesanyOf 2 | nullIm Elternobjekt erforderlich | — |
apiKey.replaced_by | arrayIm Elternobjekt erforderlich | — |
apiKey.replaced_by[] | objectOptional / Element | — |
apiKey.replaced_by[].id | stringIm Elternobjekt erforderlich |
|
apiKey.replaced_by[].name | stringIm Elternobjekt erforderlich | — |
apiKey.replaced_by[].last_4 | stringIm Elternobjekt erforderlich | — |
apiKey.replaced_by[].status | stringIm Elternobjekt erforderlich |
|
apiKey.capabilities | arrayOptional / Element | — |
apiKey.capabilities[] | stringOptional / Element |
|
apiKey.workspace_ids | array | nullOptional / Element | — |
apiKey.workspace_idsanyOf 1 | arrayOptional / Element | — |
apiKey.workspace_ids[]anyOf 1 | stringOptional / Element |
|
apiKey.workspace_idsanyOf 2 | nullOptional / Element | — |
apiKey.created_by_delegated_grant_id | string | nullOptional / Element | — |
apiKey.created_by_delegated_grant_idanyOf 1 | stringOptional / Element |
|
apiKey.created_by_delegated_grant_idanyOf 2 | nullOptional / Element | — |
secret | stringIm Elternobjekt erforderlich |
|
Vollständiges JSON Schema
{
"$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"
]
}Fehler und sichere Wiederholungen
Prüfe HTTP-Status und Antwortinhalt. Ein 400-Validierungsfehler kann einen ZodError enthalten; Handler-Fehler verwenden die Felder error, message und code. Bewahre request_id oder x-request-id zur Diagnose ohne Zugangsdaten auf. Behebe 401/403-Zugriffsfehler vor einem erneuten Versuch und beachte Retry-After bei 429. Ist ein Schreibvorgang ungewiss oder liefert 5xx, lies zuerst das bestehende Ergebnis. Verwende einen Idempotenzschlüssel nur wieder, wo dies unterstützt wird; Wiederholungen unterscheiden sich je nach Operation und garantieren keine genau einmalige Zustellung.
Anleitung zur FehlerbehebungBeispiele
Diese Beispiele nutzen anhand der Schemas geprüfte fiktive Werte. Ersetze IDs durch autorisierte IDs, Medien durch bereite Assets und Daten durch bestätigte Veröffentlichungszeiten. Prüfe Kontoeignung vor Schreibvorgängen. Diese Seite sendet keine API-Anfragen.
Setze SOSOAPI_ACCESS_TOKEN auf deinem Server auf akzeptierte Zugangsdaten dieser Operation und halte es aus Browsercode heraus. Für Agenten nutze sosoapi auth login zur Browseranmeldung und lass die CLI Zugangsdaten erneuern.
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.jsonSynthetisches Antwortbeispiel
{
"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"
}