Tema
Autenticación y alcances
La cabecera
X-API-Key: vk_live_3f9a1c72b40de5a1.hR8xK2mQ...Authorization: Bearer vk_live_... también funciona — muchos clientes van primero a esa, y un token que anuncia su propio tipo no se puede confundir con una sesión.
Qué es una llave de verdad
Una llave es la delegación del acceso de una persona, no una identidad propia. Se emite desde el puesto de alguien, y en cada petición sus alcances se intersecan con lo que esa persona tiene en ese momento.
De ahí sale una consecuencia que conviene interiorizar: una llave puede estrecharse sin que nadie la toque. Si a quien la emitió le quitan un permiso —cambia de rol, se va, un administrador ajusta su puesto— todas sus llaves lo pierden en la siguiente petición. Si pierde el puesto entero, la llave no autentica nada.
Es a propósito. La alternativa es una autorización que sobrevive a la autoridad de la que salió: alguien se va, le revocan el acceso, y la integración que montó hace seis meses sigue retirando.
Emite las llaves desde un puesto que dure más que la integración
Una llave emitida desde la cuenta de un contratista muere con el contrato, y morirá un martes por la tarde sin avisar.
Alcances
| Alcance | Qué abre |
|---|---|
portal:read | Saldos, extracto, cotizaciones y leer cualquier lista |
portal:trade | Aceptar una cotización |
portal:deposit | Billeteras de depósito y declaraciones |
portal:destinations | Registrar a dónde puede ir el dinero |
portal:withdraw | Pedir que se envíe dinero |
portal:members | La pantalla de equipo. Nunca útil para una integración. |
portal:api_keys | Emitir llaves. Inalcanzable con una llave — ver abajo. |
Dos merecen una pausa.
portal:destinations y portal:withdraw están separados a propósito. Quien tenga los dos puede mover el dinero de tu organización a una cuenta que controle, sin que participe nadie más. Una llave que sólo retire, hacia destinos que una persona registró a mano, tiene un radio de daño mucho menor que una que pueda hacer las dos cosas — y cuesta lo mismo configurarla.
Ninguna llave puede emitir otra llave. El endpoint que acuña credenciales sólo acepta a una persona con sesión iniciada. La emisión programática es cómo una llave filtrada se convierte en un punto de apoyo permanente que sobrevive a revocar la primera, así que esa puerta no existe.
Restringir desde dónde funciona
Una llave puede llevar una lista de direcciones permitidas. Si tu integración corre desde una salida fija, úsala: convierte una llave filtrada de credencial utilizable en una simple cadena de texto.
Si la salida de tu plataforma es dinámica, déjala vacía en vez de adivinar: una llave que falla de vez en cuando es peor que una sin restricción, porque tarde o temprano alguien la «arreglará» quitando la restricción con prisa.
Rotación
No hay una operación de rotar, y no es un olvido. Rotar son dos pasos que ya tienes:
- Emite una segunda llave con los mismos alcances.
- Despliégala.
- Revoca la primera.
Tu organización puede tener varias llaves vivas a la vez precisamente para que ese solapamiento sea posible. Una llave por integración, con el nombre de la integración, hace que el paso 3 sea algo que puedes hacer sin preguntarte qué se rompe.
Cuando una llave deja de funcionar
Todo fallo de autenticación responde 401 con el mismo mensaje, pase lo que pase: prefijo desconocido, secreto equivocado, revocada, caducada, dirección no permitida. Distinguirlos le ayudaría a alguien a saber qué mitad del token acertó.
Así que cuando una llave que funcionaba ayer devuelve 401, revisa en este orden:
- ¿La revocaron? Míralo en el portal. La lista conserva las revocadas y dice cuándo.
- ¿Caducó? La misma lista.
- ¿La dirección de quien llama está en su lista? Las salidas cambian sin que nadie lo decida.
- ¿Cambió el puesto de quien la emitió? La causa más común, y la menos evidente.
Un 403 es otro problema: la llave autenticó y falta el alcance. Compáralo con permissions de GET /api/v1/client, que informa la intersección que el servidor exige.
Cómo guardarla
El secreto se muestra una vez y se guarda sólo como hash — nadie puede volver a leerlo, Vectrakpital incluida. Trátalo como tratarías la contraseña de una base de datos: un gestor de secretos, no un repositorio, no un .env subido sin querer, no un mensaje de Slack.
Si estuvo donde no debía, revócala. Emitir otra toma diez segundos, y una llave de la que dudas es una llave que ya no controlas.