Claves de API y ámbitos

Cada solicitud a la API de Sursa se hace con una clave de API de su organización. Una clave pertenece a la organización, no a una persona: sigue funcionando cuando el empleado que la creó se va, y lo que puede hacer se configura en la propia clave.

Qué puede hacer una clave

Tres ajustes de una clave deciden qué puede ver y cambiar una solicitud hecha con ella. Cada uno solo restringe a los demás.

Ajuste	Qué controla
Role (rol)	`admin`, `editor`, `verifier` o `viewer`, los mismos roles que tienen las personas. La clave puede hacer lo que puede hacer un usuario con ese rol.
Scopes (ámbitos)	A qué partes de la API puede llamar la clave, por ejemplo `cards:read` o `webhooks:manage`. Consulte Ámbitos de las claves.
Data profile (perfil de datos)	Opcional. Limita la clave a las categorías de conocimiento que permite el perfil, como a un usuario con ese perfil.

Una clave también se puede limitar a algunas colecciones y recibir una fecha de caducidad. Una solicitud fuera de estos límites falla: si falta un ámbito, se devuelve 403 con el código api_keys.scope, y un objeto que la clave no puede ver devuelve 404, exactamente como si no existiera.

Dé a cada integración su propia clave con el rol y los ámbitos más restringidos que necesite. Un trabajo de sincronización que solo escribe documentos no necesita admin; un trabajo de informes no necesita ámbitos de escritura.

Crear una clave

Un administrador de la organización crea las claves en Sursa, en Administration → API keys (administración, claves de API), o con POST /v1/api-keys usando una clave o una sesión que tenga el rol admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

La respuesta contiene el valor de la clave en key. Se muestra una sola vez: Sursa solo guarda un hash de la clave y no puede volver a mostrarla. Una clave tiene la forma kb_ seguida de 43 caracteres; los primeros caracteres (prefix) se muestran en la lista de claves para que pueda distinguirlas.

Sin scopes, la clave recibe los ámbitos de su rol. Pase scopes para restringirla aún más. Sin expires_at, la clave no caduca.

Mantener las claves en secreto

Guarde las claves en un gestor de secretos o en variables de entorno de su servicio, nunca en el código fuente.
Use las claves solo desde sus servidores. Sursa acepta solicitudes desde navegadores (CORS está abierto), pero una clave en una página web la ve cualquiera que abra la página.
Nunca envíe una clave en una URL. Envíela solo en el encabezado Authorization.
Si una clave se filtra, revóquela de inmediato y cree una nueva.

Comprobar una clave

GET /v1/me devuelve la clave, su rol, sus ámbitos efectivos, su perfil de datos, su caducidad y su límite de frecuencia. Funciona con cualquier clave válida, tenga los ámbitos que tenga, así que úselo como prueba de conexión de su integración y cuando investigue un 403.

Rotar una clave

La rotación sustituye una clave sin detener la integración. La forma más rápida es rotar la clave: POST /v1/api-keys/{key_id}/roll emite un valor nuevo para la misma clave, con el mismo rol, los mismos ámbitos, las mismas colecciones y la misma caducidad. El valor anterior sigue funcionando durante overlap_hours (24 horas de forma predeterminada, hasta 168), así que mientras tanto puede desplegar el valor nuevo; POST /v1/api-keys/{key_id}/revoke-previous termina antes el solapamiento.

Para sustituir una clave por otra distinta:

Cree una clave nueva con el mismo rol, los mismos ámbitos y el mismo perfil de datos.
Despliegue la clave nueva en su integración.
Vigile la clave anterior en Administration → API keys (o last_used en GET /v1/api-keys) hasta que deje de usarse.
Revoque la clave anterior.

Asigne una fecha de caducidad a las claves y rótelas antes de que llegue. Sursa avisa a los administradores de la organización antes de que caduque una clave; una clave caducada devuelve 401 con el código api_keys.expired.

Revocar una clave

Revoque una clave en Administration → API keys o con DELETE /v1/api-keys/{key_id}. La revocación surte efecto en cuestión de segundos en todos los servidores de la API. Las solicitudes con una clave revocada devuelven 401 con el código auth.not_authenticated.

Claves de una fuente personalizada

Una fuente personalizada tiene su propio tipo de clave. Empieza por kbsrc_, solo puede escribir documentos en esa fuente y no puede leer ni buscar nada. Es la clave más segura para dar a una plataforma de integración como Zapier. Créela en la página de la fuente, en API keys (claves de API de la fuente), o con POST /v1/sources/{source_id}/push-keys.

Cuando las claves no están disponibles

Las claves de API forman parte del plan de la organización. Si el plan no las incluye, crear una clave y cualquier solicitud con una clave devuelven 403 con el código api_keys.feature_disabled.