Appearance
Claves de API
Generado desde
DialerDigital/corecommit0fc18008b3c8— especificaciónopenapi/dialer-v1.yamlv0.134.0. No se edita a mano; consulta Cómo se construye esta referencia. Descargar la especificación OpenAPI.
Traducción en curso
Esta referencia se genera desde la especificación OpenAPI. Las cadenas que todavía no tienen traducción aparecen en inglés.
Claves de API por tenant (sha256 en reposo; texto plano mostrado una vez).
Endpoints
| Método | Ruta | Resumen |
|---|---|---|
GET | /v1/api_keys | Listar las claves de API |
POST | /v1/api_keys | Emitir una clave de API |
PATCH | /v1/api_keys/{id} | Establecer la lista de permitidos de red de una clave de API |
DELETE | /v1/api_keys/{id} | Revocar una clave de API |
Listar las claves de API
http
GET /v1/api_keysSolo ids, etiquetas y marcas de tiempo de revocación — los hashes nunca se exponen.
Respuestas
200
Las claves del tenant.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
api_keys | arreglo de ApiKey | sí | |
api_keys[].id | string (uuid) | no | |
api_keys[].label | string | no | |
api_keys[].revoked_at | string (date-time) | null | no | |
api_keys[].last_used_at | string (date-time) | null | no | Reloj de higiene de rotación: la última vez que esta clave se autenticó CON ÉXITO. Se escribe como mucho una vez por minuto por clave, de modo que una lectura reciente puede ir retrasada hasta ese tiempo. null significa que no se ha autenticado con éxito desde que la columna adquirió un escritor — no que la clave nunca se haya presentado. |
api_keys[].allowed_cidrs | arreglo de string | no | Lista de permitidos de red (core#2450). [] = sin restricción. Fuera de ella, una petición se sirve y se cuenta, o se rechaza con 401, según el interruptor de tenant api_key_network_enforced (desactivado por defecto). |
api_keys[].stale | boolean | no | true para una clave viva sin usar durante 90 días (una clave que nunca se autenticó cuenta desde su creación). Consejo para que la consola rote o revoque; nada caduca por sí solo. |
api_keys[].created_by_user_id | string (uuid) | null | no | El usuario del dashboard cuya sesión emitió la clave (core#2359). null cuando la emitió otra clave dd_, el operador o las semillas, y en toda clave anterior al campo. |
api_keys[].created_at | string (date-time) | no |
json
{
"api_keys": [
{
"id": "7a3f0f7e-52a1-4f3d-9f9d-27e5a1b9c001",
"label": "onboarding",
"revoked_at": null,
"created_at": "2026-06-01T12:00:00Z"
}
]
}401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}429 — ApiKeyRateLimited
Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}Emitir una clave de API
http
POST /v1/api_keysEl token en texto plano (dd_...) se devuelve UNA vez y solo se almacena su sha256. Rota emitiendo una clave nueva y revocando la anterior.
Reglas de rol (core#2359, core#2449): emitir requiere un inicio de sesión account_admin (403 role_forbidden para un member Y, una vez que el tenant tiene un account_admin activo, para una clave dd_; interruptor por tenant api_key_admin_only, activado por defecto; interruptor del founder api_key_manages_people, desactivado por defecto). Un tenant sin account_admin activo mantiene la emisión con clave dd_. Una clave emitida desde un inicio de sesión de dashboard registra a esa persona en created_by_user_id; cada emisión se escribe en el registro de auditoría de claves.
allowed_cidrs (core#2450) es la lista de permitidos de red de la clave; omitido o [] significa sin restricción. Lo que hace una petición desde fuera de la lista es el interruptor de tenant api_key_network_enforced: desactivado (por defecto) la sirve y la cuenta, activado responde 401.
Límites (core#2503): un tenant tiene como máximo api_keys_max_live claves VIVAS (50 por defecto; 409 api_key_limit por encima, revocar una clave libera una plaza), y emitir tiene límite de uso por tenant (429 rate_limited con Retry-After). La cuota de peticiones es por clave, así que las claves de un tenant en conjunto también están acotadas por api_tenant_requests_per_minute (5x la de una clave por defecto).
Cuerpo de la petición (JSON)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
label | string | no | Etiqueta de formato libre (por defecto ""). |
allowed_cidrs | arreglo de string | no | CIDR (o direcciones simples) desde los que se puede usar la clave. Una lista con una entrada que no se puede interpretar se rechaza entera (400); un valor que no es una lista de cadenas da 422. |
json
{
"label": "postman-smoke-1751600000"
}Respuestas
201
Clave emitida; token es la única vez que el texto plano es visible.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
api_key | object (ApiKey) | sí | Metadatos de la clave — el hash del token nunca se expone. |
api_key.id | string (uuid) | no | |
api_key.label | string | no | |
api_key.revoked_at | string (date-time) | null | no | |
api_key.last_used_at | string (date-time) | null | no | Reloj de higiene de rotación: la última vez que esta clave se autenticó CON ÉXITO. Se escribe como mucho una vez por minuto por clave, de modo que una lectura reciente puede ir retrasada hasta ese tiempo. null significa que no se ha autenticado con éxito desde que la columna adquirió un escritor — no que la clave nunca se haya presentado. |
api_key.allowed_cidrs | arreglo de string | no | Lista de permitidos de red (core#2450). [] = sin restricción. Fuera de ella, una petición se sirve y se cuenta, o se rechaza con 401, según el interruptor de tenant api_key_network_enforced (desactivado por defecto). |
api_key.stale | boolean | no | true para una clave viva sin usar durante 90 días (una clave que nunca se autenticó cuenta desde su creación). Consejo para que la consola rote o revoque; nada caduca por sí solo. |
api_key.created_by_user_id | string (uuid) | null | no | El usuario del dashboard cuya sesión emitió la clave (core#2359). null cuando la emitió otra clave dd_, el operador o las semillas, y en toda clave anterior al campo. |
api_key.created_at | string (date-time) | no | |
token | string | sí | Token bearer en texto plano, mostrado exactamente una vez. |
json
{
"api_key": {
"id": "9a1c2b3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"label": "postman-smoke-1751600000",
"revoked_at": null,
"created_at": "2026-07-05T10:00:00Z"
},
"token": "dd_example_plaintext_shown_once"
}400 — BadRequest
Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).
json
{
"error": {
"code": "bad_request",
"message": "from must be RFC-3339"
}
}401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — ApiKeyAdminForbidden
Se rechazó emitir o revocar una clave de API (core#2359, adenda del ADR #46). code role_forbidden: quien llama es un inicio de sesión de dashboard sin el rol account_admin, o una clave dd_ en un tenant que ya tiene un account_admin activo (core#2449; interruptor del founder api_key_manages_people, desactivado por defecto); el interruptor por tenant api_key_admin_only (activado por defecto) desactiva esto.
json
{
"error": {
"code": "role_forbidden",
"message": "minting or revoking an API key takes a dashboard login with the account_admin role; a dd_ key may do it only while the tenant has no account_admin"
}
}409 — ApiKeyLimit
El tenant ya tiene el número máximo de claves de API VIVAS (core#2503; interruptor por tenant api_keys_max_live, 50 por defecto). code api_key_limit. No se emitió nada; revoca una clave (DELETE /v1/api_keys/{id}) y reintenta.
json
{
"error": {
"code": "api_key_limit",
"message": "this tenant already holds the maximum number of live API keys; revoke one first"
}
}422 — Unprocessable
La forma es correcta, la semántica no (regla de dominio incumplida).
json
{
"error": {
"code": "unprocessable",
"message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
}
}429 — ApiKeyRateLimited
Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}Establecer la lista de permitidos de red de una clave de API
http
PATCH /v1/api_keys/{id}Reemplaza allowed_cidrs de una clave VIVA (core#2450); [] levanta la restricción. Requiere los mismos roles que emitir (403 role_forbidden para un member mientras el interruptor api_key_admin_only esté activado). El cambio se escribe en el registro de auditoría de claves como network_changed y rige para la siguiente petición: la clave la olvida la caché de autenticación. Una clave revocada o desconocida da 404.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
id | path | string (uuid) | sí | UUID del recurso. Los ids mal formados o de otro tenant se leen como 404. |
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
allowed_cidrs | arreglo de string | sí |
json
{
"allowed_cidrs": [
"203.0.113.0/24",
"2001:db8::/32"
]
}Respuestas
200
La clave con su nueva lista.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
api_key | object (ApiKey) | sí | Metadatos de la clave — el hash del token nunca se expone. |
api_key.id | string (uuid) | no | |
api_key.label | string | no | |
api_key.revoked_at | string (date-time) | null | no | |
api_key.last_used_at | string (date-time) | null | no | Reloj de higiene de rotación: la última vez que esta clave se autenticó CON ÉXITO. Se escribe como mucho una vez por minuto por clave, de modo que una lectura reciente puede ir retrasada hasta ese tiempo. null significa que no se ha autenticado con éxito desde que la columna adquirió un escritor — no que la clave nunca se haya presentado. |
api_key.allowed_cidrs | arreglo de string | no | Lista de permitidos de red (core#2450). [] = sin restricción. Fuera de ella, una petición se sirve y se cuenta, o se rechaza con 401, según el interruptor de tenant api_key_network_enforced (desactivado por defecto). |
api_key.stale | boolean | no | true para una clave viva sin usar durante 90 días (una clave que nunca se autenticó cuenta desde su creación). Consejo para que la consola rote o revoque; nada caduca por sí solo. |
api_key.created_by_user_id | string (uuid) | null | no | El usuario del dashboard cuya sesión emitió la clave (core#2359). null cuando la emitió otra clave dd_, el operador o las semillas, y en toda clave anterior al campo. |
api_key.created_at | string (date-time) | no |
400 — BadRequest
Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).
json
{
"error": {
"code": "bad_request",
"message": "from must be RFC-3339"
}
}401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — ApiKeyAdminForbidden
Se rechazó emitir o revocar una clave de API (core#2359, adenda del ADR #46). code role_forbidden: quien llama es un inicio de sesión de dashboard sin el rol account_admin, o una clave dd_ en un tenant que ya tiene un account_admin activo (core#2449; interruptor del founder api_key_manages_people, desactivado por defecto); el interruptor por tenant api_key_admin_only (activado por defecto) desactiva esto.
json
{
"error": {
"code": "role_forbidden",
"message": "minting or revoking an API key takes a dashboard login with the account_admin role; a dd_ key may do it only while the tenant has no account_admin"
}
}404 — NotFound
Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).
json
{
"error": {
"code": "not_found",
"message": "resource not found for this tenant"
}
}422 — Unprocessable
La forma es correcta, la semántica no (regla de dominio incumplida).
json
{
"error": {
"code": "unprocessable",
"message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
}
}429 — ApiKeyRateLimited
Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}Revocar una clave de API
http
DELETE /v1/api_keys/{id}Establece revoked_at; las claves nunca se eliminan. Semántica de revocación idempotente.
Reglas de rol (core#2359, core#2449): revocar requiere un inicio de sesión account_admin (403 role_forbidden para un member Y, una vez que el tenant tiene un account_admin activo, para una clave dd_; interruptor por tenant api_key_admin_only, activado por defecto; interruptor del founder api_key_manages_people, desactivado por defecto). Un tenant sin account_admin activo mantiene la revocación con clave dd_. Toda revocación se escribe en el registro de auditoría de claves.
Parámetros
| Nombre | En | Tipo | Obligatorio | Descripción |
|---|---|---|---|---|
id | path | string (uuid) | sí | UUID del recurso. Los ids mal formados o de otro tenant se leen como 404. |
Respuestas
200
La clave revocada.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
api_key | object (ApiKey) | sí | Metadatos de la clave — el hash del token nunca se expone. |
api_key.id | string (uuid) | no | |
api_key.label | string | no | |
api_key.revoked_at | string (date-time) | null | no | |
api_key.last_used_at | string (date-time) | null | no | Reloj de higiene de rotación: la última vez que esta clave se autenticó CON ÉXITO. Se escribe como mucho una vez por minuto por clave, de modo que una lectura reciente puede ir retrasada hasta ese tiempo. null significa que no se ha autenticado con éxito desde que la columna adquirió un escritor — no que la clave nunca se haya presentado. |
api_key.allowed_cidrs | arreglo de string | no | Lista de permitidos de red (core#2450). [] = sin restricción. Fuera de ella, una petición se sirve y se cuenta, o se rechaza con 401, según el interruptor de tenant api_key_network_enforced (desactivado por defecto). |
api_key.stale | boolean | no | true para una clave viva sin usar durante 90 días (una clave que nunca se autenticó cuenta desde su creación). Consejo para que la consola rote o revoque; nada caduca por sí solo. |
api_key.created_by_user_id | string (uuid) | null | no | El usuario del dashboard cuya sesión emitió la clave (core#2359). null cuando la emitió otra clave dd_, el operador o las semillas, y en toda clave anterior al campo. |
api_key.created_at | string (date-time) | no |
401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — ApiKeyAdminForbidden
Se rechazó emitir o revocar una clave de API (core#2359, adenda del ADR #46). code role_forbidden: quien llama es un inicio de sesión de dashboard sin el rol account_admin, o una clave dd_ en un tenant que ya tiene un account_admin activo (core#2449; interruptor del founder api_key_manages_people, desactivado por defecto); el interruptor por tenant api_key_admin_only (activado por defecto) desactiva esto.
json
{
"error": {
"code": "role_forbidden",
"message": "minting or revoking an API key takes a dashboard login with the account_admin role; a dd_ key may do it only while the tenant has no account_admin"
}
}404 — NotFound
Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).
json
{
"error": {
"code": "not_found",
"message": "resource not found for this tenant"
}
}429 — ApiKeyRateLimited
Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (core#2503) (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.
json
{
"error": {
"code": "rate_limited",
"message": "API key request quota exceeded; retry after the interval in Retry-After"
}
}