> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Intercambiar una clave de acceso por un token al portador > Intercambiar el par de claves de acceso de una cuenta de servicio por un token portador de corta duración, y luego enviar ese token como `Authorization: Bearer ` en cada otra llamada. Esta es la forma habitual de autenticación. El par de claves de acceso sigue siendo la única credencial de larga duración que tiene una cuenta de servicio; lo que cambia es que presentas un token derivado de él en lugar de firmar cada solicitud. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` El mismo par de claves es *también* la credencial de AWS SigV4 para el punto final de objeto compatible con S3, lo que no dice nada más. Usa el token para esta API y el par de claves para S3; no es necesario elegir. **Los errores aquí usan la forma OAuth 2.0, no el sobre habitual de esta API** — `{"error": "...", "error_description": "..."}` — porque cada biblioteca cliente OAuth analiza eso y nada más. Dos respuestas importan y sus remedios son opuestos. `invalid_client` significa que la clave fue rechazada: compruébela o rótela. `invalid_grant` significa que la clave está bien y la organización está suspendida o todavía en proceso de incorporación, donde rotar una clave de trabajo le haría perder tiempo. Una clave de acceso desconocida y un secreto incorrecto responden a `invalid_client` con el mismo mensaje, por lo que el punto final no puede ser utilizado para descubrir qué claves existen. Requiere **sin acción de IAM**. El acceso se decide por las propias reglas del punto final en lugar de por una política. Consulte la descripción anterior. ## OpenAPI ````yaml /es/api-reference/specs/iam.yaml post /v1/oauth/token openapi: 3.0.3 info: title: API de Basaltic IAM version: 1.0.0 description: > Administración de identidad y acceso de cuentas: cuentas de servicio, roles, directivas de cuenta y sesiones temporales con ámbito de cuenta. La autenticación y el inicio de sesión personal permanecen en IAM. Las organizaciones, cuentas, usuarios, grupos y directivas de organización se administran mediante la API de Workspace. Las funciones y las políticas personalizadas pertenecen a la cuenta seleccionada. Sus CRN globales usan una región vacía y el identificador de la cuenta propietaria.Las entradas de relación se clasifican una vez como CRN, UUID o nombre, sin fallback de sintaxis. AssumeRole resuelve la cuenta propietaria del rol de destino. El llamador necesita permiso de origen y el rol de destino debe confiar en el llamador; la sesión resultante usa solo los permisos del rol de destino, sujeto a límites y restricciones de sesión. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://iam.basaltic.sh description: Endpoint de API global security: - BearerAuth: [] paths: /v1/oauth/token: post: tags: - IAM summary: Intercambiar una clave de acceso por un token al portador description: > Intercambiar el par de claves de acceso de una cuenta de servicio por un token portador de corta duración, y luego enviar ese token como `Authorization: Bearer ` en cada otra llamada. Esta es la forma habitual de autenticación. El par de claves de acceso sigue siendo la única credencial de larga duración que tiene una cuenta de servicio; lo que cambia es que presentas un token derivado de él en lugar de firmar cada solicitud. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` El mismo par de claves es *también* la credencial de AWS SigV4 para el punto final de objeto compatible con S3, lo que no dice nada más. Usa el token para esta API y el par de claves para S3; no es necesario elegir. **Los errores aquí usan la forma OAuth 2.0, no el sobre habitual de esta API** — `{"error": "...", "error_description": "..."}` — porque cada biblioteca cliente OAuth analiza eso y nada más. Dos respuestas importan y sus remedios son opuestos. `invalid_client` significa que la clave fue rechazada: compruébela o rótela. `invalid_grant` significa que la clave está bien y la organización está suspendida o todavía en proceso de incorporación, donde rotar una clave de trabajo le haría perder tiempo. Una clave de acceso desconocida y un secreto incorrecto responden a `invalid_client` con el mismo mensaje, por lo que el punto final no puede ser utilizado para descubrir qué claves existen. operationId: getOAuthToken requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/OAuthTokenRequest' application/json: schema: $ref: '#/components/schemas/OAuthTokenRequest' responses: '200': description: Un token portador content: application/json: schema: $ref: '#/components/schemas/OAuthTokenResponse' '400': description: > Solicitud mal formada o un tipo de concesión que esta implementación no sirve. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: unsupported_grant_type error_description: unsupported grant type '401': description: > Falló la autenticación del cliente: una clave de acceso desconocida, un secreto incorrecto o una clave deshabilitada o caducada. Una respuesta abarca a todos ellos. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: invalid_client error_description: client authentication failed '403': description: > La credencial es válida pero la organización no está activa. No hay nada malo con la llave. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: invalid_grant error_description: Organization is suspended '429': $ref: '#/components/responses/TooManyRequests' '503': description: > No se pudo completar el intercambio. La credencial no fue rechazada, vuelva a intentarlo en lugar de rotarla. content: application/json: schema: $ref: '#/components/schemas/OAuthError' example: error: temporarily_unavailable error_description: try again shortly security: [] components: schemas: OAuthTokenRequest: type: object description: > Una solicitud de token OAuth 2.0. La codificación de formularios es lo que especifica RFC 6749 y lo que envían las bibliotecas cliente; también se acepta JSON. Las credenciales del cliente pueden ser enviadas como HTTP Basic (`Authorization: Basic base64(key_id:secret)`, que es lo que la mayoría de las bibliotecas hacen por defecto) o como `client_id` y `client_secret` campos. Básico gana si ambos están presentes. required: - grant_type properties: grant_type: type: string enum: - client_credentials - authorization_code - refresh_token description: > `client_credentials` es el que se usa para una cuenta de servicio: intercambia un par de claves de acceso por un token, y no necesita nada más. `authorization_code` y `refresh_token` pertenecen al login interactivo que ejecuta una persona (`basaltic login`), donde el token nombra a un USER en lugar de una cuenta de servicio. Son impulsados por la CLI, no escritos a mano. Compruebe el documento de metadatos del servidor de autorización antes de ramificarse en ellos; solo se anuncian cuando se configura un punto final de autorización. example: client_credentials client_id: type: string description: El id de la clave de acceso. Omita cuando use HTTP Basic. example: BYCLD1a2b3c4d5e6f7 client_secret: type: string format: password description: La clave de acceso secreta. Omita cuando use HTTP Basic. duration_seconds: type: integer minimum: 900 maximum: 43200 description: > Vida útil del token solicitado. Una extensión de Basaltic, no un parámetro de OAuth — omítelo y obtendrás el valor predeterminado. Los valores fuera del rango se fijan en él en lugar de rechazarse, por lo que pedir un día produce el token más largo permitido. example: 3600 code: type: string description: > El código de autorización de la redirección de consentimiento. Uso único, y válido por cinco minutos. `authorization_code` concede solo. code_verifier: type: string description: > El verificador PKCE cuyo SHA-256 fue enviado como `code_challenge` cuando el flujo comenzó (RFC 7636). Requerido con `authorization_code`: es lo que prueba que este es el cliente que inició el flujo, ya que una CLI no tiene secreto de cliente. redirect_uri: type: string description: > El mismo `redirect_uri` para el que se emitió el código — para la CLI, `urn:ietf:wg:oauth:2.0:oob`. Se vuelve a comprobar aquí, por lo que un código no se puede canjear bajo otro diferente (RFC 6749 4.1.3). example: urn:ietf:wg:oauth:2.0:oob refresh_token: type: string description: > `refresh_token` concede solo. Renueva una sesión de usuario sin otro viaje a través del navegador. Rotar en cada uso - guardar el nuevo. OAuthTokenResponse: type: object description: Respuesta de token RFC 6749. required: - access_token - token_type - expires_in properties: access_token: type: string description: > Enviar como `Authorization: Bearer `. Opaca para los clientes: no la analiza, y no introduce nada en la cadena de token. example: eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9... token_type: type: string enum: - Bearer example: Bearer expires_in: type: integer description: Segundos hasta que caduque el token. example: 3600 refresh_token: type: string description: > Devuelto solo por las concesiones del usuario (`authorization_code` y `refresh_token`). Presente la licencia `refresh_token` para renovarla sin otro viaje de ida y vuelta del navegador; se ROTA en cada uso, por lo que reemplaza la copia almacenada cada vez. Una cuenta de servicio no obtiene ninguna. Ya tiene una clave de acceso de larga duración y puede simplemente ejecutar `client_credentials` de nuevo, por lo que un token de actualización sería una segunda credencial para almacenar sin ningún beneficio. OAuthError: type: object description: > Respuesta de error RFC 6749. Deliberadamente NO el sobre de error habitual de esta API: las bibliotecas de clientes OAuth analizan esta forma y nada más, y el punto principal del punto final del token es que un cliente de stock puede llegar a él. required: - error properties: error: type: string enum: - invalid_request - invalid_client - invalid_grant - unsupported_grant_type - temporarily_unavailable - server_error description: > `invalid_client` — la clave fue rechazada; compruébela o rótela. `invalid_grant` — la clave está bien, la organización no está activa. Esos dos tienen remedios opuestos y vale la pena distinguirlos antes de que alguien rote una credencial de trabajo. example: invalid_client error_description: type: string description: Detalle legible por el ser humano. No coincida en él. example: client authentication failed Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Código de error que identifica el tipo de error example: INVALID_INPUT message: type: string description: Mensaje de error legible por el ser humano example: Invalid request parameters params: type: object additionalProperties: true description: >- Valores no sensibles opcionales para la interpolación de errores localizados, codificados por código de error. Nunca presente por errores del servidor. example: instances: 2 pools: 0 request_id: type: string format: uuid description: Solicitar ID para depuración example: 550e8400-e29b-41d4-a716-446655440000 responses: TooManyRequests: description: > Límite de velocidad excedido. El presupuesto es una ventana fija contada por punto final y por llamador (el principal autenticado cuando la solicitud lleva credenciales, la IP del cliente de lo contrario), de modo que un punto final con restricción nunca gasta el presupuesto de otro, y un inquilino nunca gasta el de otro. Espere `Retry-After` segundos, luego vuelva a intentarlo. Los encabezados `X-RateLimit-*` también se basan en las respuestas exitosas de un punto final con límite de velocidad, por lo que un cliente puede acelerarse en lugar de descubrir el límite al alcanzarlo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMITED message: Too many requests, please try again later request_id: 550e8400-e29b-41d4-a716-446655440000 headers: Retry-After: description: Segundos para esperar antes de volver a intentarlo. Nunca a cero. required: true schema: type: integer minimum: 1 example: 42 X-RateLimit-Limit: description: Solicitudes permitidas por ventana en este punto final. required: true schema: type: integer minimum: 1 example: 5 X-RateLimit-Remaining: description: Solicitudes que quedan en la ventana actual. Siempre 0 en un 429. required: true schema: type: integer minimum: 0 example: 0 X-RateLimit-Reset: description: >- Segundos hasta que la ventana se reinicia: una duración, no una marca de tiempo, por lo que no necesita ningún acuerdo de reloj entre el cliente y el servidor. required: true schema: type: integer minimum: 1 example: 42 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >+ Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer `. Esta es la forma recomendada de autenticación. Obtén el token intercambiando el par de claves de acceso de una cuenta de servicio en `POST /v1/oauth/token` con `grant_type=client_credentials`. Es el flujo estándar de credenciales de cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar el token por ti. ``` curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \ https://iam.basaltic.sh/v1/oauth/token ``` Los tokens duran una hora por defecto. El mismo par de claves de acceso también sirve como credencial AWS SigV4 para el endpoint de objetos compatible con S3, que solo acepta ese método de autenticación. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.