Cuentas y espacios de trabajo
Crear clave API
Crea una clave de acceso personal con las capacidades elegidas (agent:operate, agent:publish, agent:engage), un límite opcional workspace_ids y una vigencia de hasta 365 días; el secreto se devuelve una sola vez y no puede volver a consultarse. Un agente solo puede conceder lo que permite su propia autorización, durante un máximo de 30 días, y la clave deja de funcionar cuando termina esa concesión. Requiere el permiso para administrar claves API; un PAT no puede usarlo.
POST /identity-api/api-keys/createContrato revisado: · sha256:563d2d581da0ad29
Descripción general
Crea una clave de acceso personal con las capacidades elegidas (agent:operate, agent:publish, agent:engage), un límite opcional workspace_ids y una vigencia de hasta 365 días; el secreto se devuelve una sola vez y no puede volver a consultarse. Un agente solo puede conceder lo que permite su propia autorización, durante un máximo de 30 días, y la clave deja de funcionar cuando termina esa concesión. Requiere el permiso para administrar claves API; un PAT no puede usarlo.
Cada autorización delegada puede tener hasta 25 claves activas. Las solicitudes por encima de ese límite devuelven API_KEY_GRANT_KEY_LIMIT.
Una respuesta HTTP exitosa puede indicar aceptación, no finalización. Para trabajo en segundo plano, guarda el ID devuelto y consulta la misma operación hasta que termine. Una publicación programada o aceptada solo está publicada cuando la plataforma lo confirma; un tiempo de espera agotado en el cliente no determina el resultado.
Autenticación y permisos
Un token solo puede usar los derechos de su propietario. Cada solicitud comprueba pertenencia al espacio, propiedad del recurso, espacios elegidos y capacidades concedidas. Los perfiles core y full cambian qué herramientas se muestran; no conceden acceso.
Campos de solicitud
Obligatorio significa obligatorio dentro del objeto principal y la rama elegida. Un campo secundario obligatorio no convierte en obligatorio un objeto principal opcional. Las reglas y nombres de campos siguientes se copian del contrato.
| Campo / rama | Tipo / obligatorio | Restricciones |
|---|---|---|
$ | objectObligatorio en el objeto principal |
|
name | stringObligatorio en el objeto principal |
|
lifetime_days | integerOpcional / elemento | Días hasta el vencimiento de la clave (1-365, predeterminado 365). Una clave creada por un agente delegado nunca dura más de 30 días.
|
capabilities | arrayOpcional / elemento | Qué puede hacer la clave. Para un usuario con sesión iniciada, los valores predeterminados son operate, publish y engage. Un agente delegado solo puede conceder lo que permite su propia autorización (nunca gestión de claves).
|
capabilities[] | stringOpcional / elemento |
|
workspace_ids | arrayOpcional / elemento | Limita la clave a estos espacios de trabajo. Omítelo para todos los espacios a los que puede acceder el usuario. Una clave limitada debe indicar su espacio (workspace_id) en rutas que usarían el activo y no puede consultar datos de toda la organización.
|
workspace_ids[] | stringOpcional / elemento |
|
scopes | arrayOpcional / elemento | Alias obsoleto de capabilities. Se respeta exactamente; se ignora una lista vacía.
|
scopes[] | stringOpcional / elemento |
|
idempotency_key | stringOpcional / elemento | Opcional. Reutiliza la misma clave para reintentar con seguridad. El secreto se muestra una sola vez: un reintento que encuentra la clave ya creada responde 409 IDEMPOTENT_REPLAY (details.existing_key la identifica) en vez de mostrarlo de nuevo. Revoca esa clave y crea otra con un idempotency_key nuevo.
|
JSON Schema completo
{
"$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
}Respuesta y finalización
Estados HTTP de éxito: 200. Cuando la operación se completa: synchronous_http_response.
Una respuesta HTTP exitosa puede indicar aceptación, no finalización. Para trabajo en segundo plano, guarda el ID devuelto y consulta la misma operación hasta que termine. Una publicación programada o aceptada solo está publicada cuando la plataforma lo confirma; un tiempo de espera agotado en el cliente no determina el resultado.
Obligatorio significa obligatorio dentro del objeto principal y la rama elegida. Un campo secundario obligatorio no convierte en obligatorio un objeto principal opcional. Las reglas y nombres de campos siguientes se copian del contrato.
| Campo / rama | Tipo / obligatorio | Restricciones |
|---|---|---|
$ | objectObligatorio en el objeto principal | — |
apiKey | objectObligatorio en el objeto principal | — |
apiKey.id | stringObligatorio en el objeto principal |
|
apiKey.name | stringObligatorio en el objeto principal | — |
apiKey.last_4 | stringObligatorio en el objeto principal | — |
apiKey.scopes | arrayObligatorio en el objeto principal | — |
apiKey.scopes[] | stringOpcional / elemento | — |
apiKey.created_at | stringObligatorio en el objeto principal |
|
apiKey.expires_at | string | nullObligatorio en el objeto principal | — |
apiKey.expires_atanyOf 1 | stringObligatorio en el objeto principal |
|
apiKey.expires_atanyOf 2 | nullObligatorio en el objeto principal | — |
apiKey.last_used_at | string | nullObligatorio en el objeto principal | — |
apiKey.last_used_atanyOf 1 | stringObligatorio en el objeto principal |
|
apiKey.last_used_atanyOf 2 | nullObligatorio en el objeto principal | — |
apiKey.revoked_at | string | nullObligatorio en el objeto principal | — |
apiKey.revoked_atanyOf 1 | stringObligatorio en el objeto principal |
|
apiKey.revoked_atanyOf 2 | nullObligatorio en el objeto principal | — |
apiKey.status | stringObligatorio en el objeto principal |
|
apiKey.replaces | object | nullObligatorio en el objeto principal | — |
apiKey.replacesanyOf 1 | objectObligatorio en el objeto principal | — |
apiKey.replaces.idanyOf 1 | stringObligatorio en el objeto principal |
|
apiKey.replaces.nameanyOf 1 | stringObligatorio en el objeto principal | — |
apiKey.replaces.last_4anyOf 1 | stringObligatorio en el objeto principal | — |
apiKey.replaces.statusanyOf 1 | stringObligatorio en el objeto principal |
|
apiKey.replacesanyOf 2 | nullObligatorio en el objeto principal | — |
apiKey.replaced_by | arrayObligatorio en el objeto principal | — |
apiKey.replaced_by[] | objectOpcional / elemento | — |
apiKey.replaced_by[].id | stringObligatorio en el objeto principal |
|
apiKey.replaced_by[].name | stringObligatorio en el objeto principal | — |
apiKey.replaced_by[].last_4 | stringObligatorio en el objeto principal | — |
apiKey.replaced_by[].status | stringObligatorio en el objeto principal |
|
apiKey.capabilities | arrayOpcional / elemento | — |
apiKey.capabilities[] | stringOpcional / elemento |
|
apiKey.workspace_ids | array | nullOpcional / elemento | — |
apiKey.workspace_idsanyOf 1 | arrayOpcional / elemento | — |
apiKey.workspace_ids[]anyOf 1 | stringOpcional / elemento |
|
apiKey.workspace_idsanyOf 2 | nullOpcional / elemento | — |
apiKey.created_by_delegated_grant_id | string | nullOpcional / elemento | — |
apiKey.created_by_delegated_grant_idanyOf 1 | stringOpcional / elemento |
|
apiKey.created_by_delegated_grant_idanyOf 2 | nullOpcional / elemento | — |
secret | stringObligatorio en el objeto principal |
|
JSON Schema completo
{
"$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"
]
}Errores y reintentos seguros
Comprueba el estado HTTP y el cuerpo de respuesta. Un error de validación 400 puede contener un ZodError; los errores del controlador usan los campos error, message y code. Conserva request_id o x-request-id para el diagnóstico, sin credenciales. Corrige los errores de acceso 401/403 antes de reintentar y respeta Retry-After para 429. Si una escritura es incierta o devuelve 5xx, consulta primero el resultado existente. Reutiliza una clave de idempotencia solo donde se admita; el comportamiento de reintento varía por operación y no garantiza una entrega exactamente una vez.
Guía de solución de problemasEjemplos
Estos ejemplos usan valores ficticios comprobados con los esquemas. Sustituye los IDs por otros autorizados, los archivos multimedia por recursos listos y las fechas por tu hora de publicación confirmada. Comprueba la elegibilidad de la cuenta antes de enviar una escritura. Esta página no envía solicitudes API.
Establece SOSOAPI_ACCESS_TOKEN en tu servidor con una credencial aceptada por esta operación y mantenla fuera del código del navegador. Para un agente, usa sosoapi auth login para iniciar sesión en el navegador y deja a la CLI renovar sus credenciales.
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.jsonEjemplo de respuesta sintética
{
"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"
}