Ir al contenido
Sursa Developers

POST/v1/api-keys

Crear una clave de API

create_api_key

Autenticación

Envíe una clave de API en el encabezado Authorization: Authorization: Bearer <clave>.

Parámetros de encabezado

  • Idempotency-Keystring

    Clave para reintentar de forma segura una escritura: de 1 a 255 caracteres ASCII imprimibles; se recomienda un UUID v4 por operación lógica. Un reintento con la misma clave en un plazo de 24 horas no vuelve a ejecutar la operación: devuelve la respuesta guardada (estado, encabezados y cuerpo) con el encabezado Idempotency-Replayed: true. La misma clave con otro método, otra ruta, otro Content-Type u otro cuerpo devuelve 409 api.idempotency_mismatch; mientras la primera solicitud sigue en curso, 409 api.idempotency_in_progress con Retry-After: 1. Tras una respuesta 5xx o 429, la clave se libera y un reintento vuelve a ejecutar la operación. La clave se aplica a la organización y a quien llama a la API (clave de API, usuario o clave de fuente personalizada).

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    Solo para claves de API con el rol admin. Ejecuta la solicitud como el perfil de datos <profile>[:viewer|verifier|editor], por ejemplo employee:viewer. La clave de instalación no puede usar este encabezado (403).

Parámetros de cookie

  • kb_view_asstring

    Cookie del modo «View as» para una sesión. POST /auth/view-as la establece y DELETE /auth/view-as la elimina.

Cuerpo de la solicitud

application/json

Objeto: ApiKeyCreate

  • namestringobligatorio

    length ≥ 1, length ≤ 64

  • rolestring

    Predeterminado: "editor"

  • data_profilestring | null

    Perfil de datos de la clave. Sin él, la clave recibe el perfil predeterminado de la organización. Un perfil de datos no se aplica al rol admin. Una clave de administrador ve todos los datos de la organización, y un perfil distinto de full devuelve 400 api_keys.data_profile_not_applicable.

  • expires_atstring (date-time) | null

    Momento de caducidad de la clave (ISO 8601, en el futuro). null o sin valor: la clave no caduca.

  • scopesarray of ApiKeyScope | null

    Ámbitos de la clave. Si no se indican, los ámbitos dependen del rol: admin recibe read, write, admin; editor y verifier reciben read, write; viewer recibe read. El ámbito system solo lo emite el administrador de la instalación. También se aceptan ámbitos detallados resource:action (ApiKeyScope); los anteriores read, write y admin se expanden en conjuntos de ámbitos.

  • collection_idsarray of integer | null

    Limita la clave a estas colecciones de la organización. Las tarjetas, la búsqueda, las respuestas y los eventos solo funcionan en ellas, además de lo que permiten el rol y el perfil de datos. Sin valor o con una lista vacía, no hay restricción. Si la propia clave que llama está limitada a colecciones, la clave nueva solo puede estar en sus colecciones. Sin este campo, la clave nueva recibe las colecciones de la clave que llama. Una lista vacía o una colección fuera de su lista devuelven 400 api_keys.invalid_collections.

    items ≤ 100

  • allowed_cidrsarray of string | null

    Redes desde las que se puede usar la clave, como 10.0.0.0/8 o 2001:db8::/32. Una sola dirección es una red de una dirección. Una solicitud desde otra dirección devuelve 403 api_keys.ip_not_allowed. Sin valor, no hay restricción.

    items ≤ 50

Respuestas

200Respuesta correcta

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

  • Idempotency-Replayed

    true significa que la respuesta se reprodujo a partir de la guardada para esta Idempotency-Key: la operación no se volvió a ejecutar.

application/json

Objeto: ApiKeyCreated

  • idintegerobligatorio
  • namestringobligatorio
  • prefixstringobligatorio
  • roleRoleobligatorio
  • created_atstring (date-time)obligatorio
  • keystringobligatorio
  • data_profilestring | nullobligatorio
  • expires_atstring (date-time)

    Momento de caducidad. Solo aparece en las claves con caducidad.

  • scopesarray of string

    Ámbitos explícitos de la clave. Solo aparece en las claves con ámbitos definidos explícitamente.

  • collection_idsarray of integer

    Restricción por colecciones. Solo aparece en las claves con restricción.

  • allowed_cidrsarray of string

    Redes permitidas. Solo aparece en las claves con restricción.

400La solicitud no es válida: el valor de un parámetro o el estado del objeto no permiten la acción (`detail` es un mensaje).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

401No se enviaron credenciales (ni una cookie de sesión ni una clave de API) o no se encontró la clave.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

403La acción no está permitida: el rol no es suficiente, no hay acceso a la colección o a la tarjeta, la solicitud se ejecuta en modo «View as», o la organización está suspendida o eliminada (`detail` es un objeto con `code: org_suspended | org_deleted`).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

422Error de validación: el cuerpo o los parámetros no coinciden con el esquema (`detail` es una lista de errores de validación), o el valor de un parámetro está fuera del rango permitido (`detail` es un mensaje).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

429Demasiadas solicitudes (`api.rate_limited`), se agotó la cuota de la organización para el minuto, el día o el mes (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` y `reset_at`), se alcanzó el límite de la organización o el servicio de respuestas está ocupado (`answers.engine_busy`). Espere el tiempo indicado en el encabezado `Retry-After`.

Encabezados de la respuesta

  • Retry-After

    Número de segundos que hay que esperar antes de reintentar la solicitud.

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

    Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

Códigos de error

Códigos que este endpoint puede devolver en error.code, además de los códigos generales de cualquier solicitud.

Reintentos seguros

Envíe un encabezado Idempotency-Key (por ejemplo, un UUID) con cada POST y PATCH. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta guardada en lugar de volver a ejecutar la solicitud.

Límites de frecuencia

Las respuestas incluyen los encabezados RateLimit y RateLimit-Policy y los anteriores X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta 429 lleva Retry-After en segundos: espere y vuelva a intentarlo.

← api-keys · Referencia de la API