basaltic login, que abre un navegador y devuelve un token que actúa como ellos. Ambos usan Authorization: Bearer. El acceso personal a la organización y el acceso de rol de cuenta son independientes: todos los humanos asumen un rol de cuenta asignado antes de realizar solicitudes de servicio de cuenta.
La diferencia no es cosmética. Una cuenta de servicio no puede crear una organización, aceptar una invitación o cambiar de organización; para ello, se necesita una persona. Si la CLI le dice que una operación requiere un usuario, eso es lo que significa.
El mismo par de claves también es su credencial de AWS Signature versión 4 para el extremo de objeto compatible con S3, que no dice nada más. Una credencial, dos presentaciones y ninguna elección que hacer en el momento de la solicitud: token para esta API, par de claves para S3.
Cómo obtener credenciales
Las claves de acceso pertenecen a una cuenta de servicio, nunca a una persona. Cree uno, déle una política y luego cree una credencial en él — vea el inicio rápido. El secreto se muestra una vez, en la creación, y nunca más. Para credenciales de corta duración, consulte Credenciales temporales para un rol A continuación.Cómo obtener un token
client_id y client_secret campos de formulario.
Luego envíelo en cada llamada:
Validez del token
Una hora por defecto. Pida otro conduration_seconds, entre 900 y 43200. Un valor fuera de ese rango se bloquea en lugar de rechazarse, por lo que pedir un día le da el token más largo permitido.
Tratar el token como opaco. No la analice, y no use la cadena de token como una clave en una caché, una lista de denegación o una tabla de deduplicación — una firma tiene varias codificaciones válidas, por lo que un token puede aparecer como varias cadenas diferentes.
Cuando se rechaza una solicitud
Dos respuestas se parecen y tienen remedios opuestos:
Una clave de acceso desconocida y una respuesta secreta incorrecta de forma idéntica, por lo que el punto final no se puede utilizar para descubrir qué claves existen.
Los errores aquí usan la forma OAuth 2.0 —
{"error": ..., "error_description": ...} — en lugar del sobre habitual de esta API, porque eso es lo que las bibliotecas cliente OAuth analizan.
Cómo revocar un token
200 si algo fue revocado o no — un punto final que te dijera la diferencia le diría a cualquiera que tenga un token si todavía funciona.
Cómo iniciar sesión con tu identidad personal
~/.config/basaltic/credentials.yaml, modo 0600, separado de config.yaml para que tu configuración sea segura para compartir.
El navegador no tiene que estar en la misma máquina. Esa es la razón por la que es un código y no una redirección: abra la URL en su computadora portátil, lleve el código al terminal en el servidor en el que está trabajando. Una redirección tendría que aterrizar en algún lugar, y “algún lugar” es siempre la máquina que ejecuta el navegador.
Use esto cuando usted es una persona en una terminal. Utilice una tecla de acceso cuando el llamador es un programa que tiene que ejecutarse sin usted.
Bajo el capó es un código de autorización OAuth 2.0 con PKCE, entregado fuera de banda (redirect_uri=urn:ietf:wg:oauth:2.0:oob). Vale la pena conocer algunas consecuencias:
- La CLI no contiene ningún secreto de cliente. Se envía a computadoras portátiles, por lo que cualquier secreto que contenga sería legible por cualquier persona que tenga el binario. Lo que protege el flujo es PKCE: canjear el código requiere de un verificador que genera la CLI cuando el flujo se inicia y no envía hasta el momento en que gasta el código. Ver el código no es suficiente para usarlo.
- El código es de un solo uso y dura cinco minutos. Se gasta por el intento, no por el éxito, por lo que un código interceptado no puede ser reintentado contra verificadores adivinados.
- Pega solo en la terminal que iniciaste. Un código no vale nada sin el verificador que tiene el proceso que lo pidió, así que pegar uno en otro programa no logra nada — pero un programa que te lo pide no está haciendo nada para lo que te necesita.
basaltic auth status muestra quién eres, en qué organización estás y cuándo caduca la credencial. basaltic auth logout lo revoca.
Las máquinas desatendidas (un ejecutante CI, un trabajo cron) deberían usar una clave de acceso de cuenta de servicio en lugar de este flujo. Necesita una persona para aprobarlo, y un token que actúa como una persona es lo incorrecto para el trabajo desatendido de todos modos.
Credenciales temporales para un rol
POST /v1/assume-role en iam.basaltic.sh emite credenciales para un rol en su organización. La suposición entre cuentas necesita tanto un permiso de origen iam:AssumeRole como una confianza de destino. Las asignaciones de rol de cuenta humana proporcionan el permiso de origen; no cambian la directiva de confianza. La respuesta lleva ambos formularios de una sesión: un access_token para esta API, y el SigV4 cuatro para S3. Comparten un vencimiento, y revocar la sesión detiene ambos.
Las instancias obtienen el mismo par del servicio de metadatos: la ruta compatible con AWS para las credenciales de S3 y /latest/basaltic/iam/access-token para el token.
La respuesta también incluye account_id, account_handle, y role_id. Verifique estos datos con el objetivo que ha seleccionado. Una sesión utiliza los permisos del rol de destino, sin unir permisos de su origen.
La consola mantiene un token personal para las páginas de espacio de trabajo y un token de rol de cuenta seleccionado por separado. Las integraciones deben preservar la misma distinción. Consulte account access y roles.
Solicitud de firma (retirada)
Las API de plano de control aceptan tokens de portador. No se aceptan firmas de solicitudBASALTIC-HMAC-SHA256 heredadas. Intercambiar credenciales de cuenta de servicio a través de /v1/oauth/token, o usar access_token de una respuesta de AssumeRole.
El punto final de objeto compatible con S3 utiliza la versión 4 de AWS Signature estándar. Cuando utilice credenciales temporales, proporcione el token de sesión a través de la opción de token de sesión del SDK de AWS. Las solicitudes de plano de control no utilizan la firma S3.
Límites de tasa
No hay presupuesto global de solicitud. Un límite se aplica solo cuando una operación documenta un429, y cada uno de estos puntos finales cuenta su propia ventana fija. Todo lo demás está limitado por la cuota en lugar de por la tasa de solicitud.
Los puntos finales limitados aquí son los dos públicos, no autenticados — GET /v1/regions y el catálogo de precios GET /v1/prices — que se cuentan por IP de cliente porque no hay principal para contar. Las respuestas — 429 y 2xx por igual — llevan X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset para que puedas irte a tu ritmo en lugar de descubrir el techo al golpearlo. Lee X-RateLimit-Limit en lugar de codificar un número.
En un 429, honra Retry-After. El reintento antes de la fecha se rechaza y extiende la ventana, porque el intento rechazado se cuenta en sí mismo.
Algunos recursos miden el trabajo en lugar de la solicitud (el envío de un mensaje está limitado por identidad por segundo) y documentan su propio 429 en la operación.