Autenticación de APIs con API Keys y OAuth 2.0

Autenticación de APIs con API Keys y OAuth 2.0

Resumen

Esta guía explica cómo identificar una aplicación en el Portal, obtener sus credenciales y autenticar solicitudes a las APIs mediante API Keys u OAuth 2.0.

Los ejemplos utilizan valores ficticios. Reemplácelos por los datos de su aplicación y por la URL que figure en la documentación del método.

Antes de comenzar

  • Debe contar con un usuario registrado e iniciar sesión en el Portal para desarrolladores.
  • Debe tener una aplicación creada y con acceso al método que desea consumir.
  • Revise en la documentación del método el esquema de autenticación, la URL, los parámetros y los permisos disponibles.

Dónde encontrar las credenciales

Abra el menú de usuario, ingrese en Mi cuenta y seleccione Mis aplicaciones. Cada aplicación muestra las Llaves de acceso y, cuando corresponde, las credenciales OAuth 2.0. Use el ícono de visualización únicamente en un entorno privado.

Autenticación con API Keys

Las aplicaciones pueden mostrar una Auth Key y una Public Auth Key. La documentación del método indica la llave y la forma de envío esperadas. No intercambie ambas credenciales ni agregue el prefijo Bearer salvo que el método lo solicite expresamente.

Enviar la API Key como parámetro

Cuando el método indica envío por parámetro, agregue auth_key a la URL:
GET https://api.example.com/accounts/v1/accounts.json?auth_key=YOUR_AUTH_KEY

Enviar la API Key en una cabecera

Cuando el método indica envío por cabecera, utilice Authorization con la llave como valor:
curl --request GET \
  --header 'Authorization: YOUR_AUTH_KEY' \
  'https://api.example.com/accounts/v1/accounts.json'

Autenticación con OAuth 2.0

El flujo mostrado en el portal es Client Credentials. Primero se solicita un access token con el Client Id y el Client Secret; después se envía ese token en cada llamada a la API.

Obtener un token desde el portal

En la documentación del método, haga clic en Probar método, seleccione la aplicación y pulse Obtener token de acceso. El portal muestra el token y su vigencia. En el ejemplo, la vigencia informada es de 86400 segundos; confirme siempre el valor expires_in de la respuesta actual.


Solicitar un token con cURL

Realice una solicitud POST al endpoint /oauth/token/ con Content-Type: application/x-www-form-urlencoded:
curl --location --request POST 'https://YOUR_DOMAIN/oauth/token/' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=read'
El scope read es el utilizado en el ejemplo. Solicite solo los scopes que aparecen como requeridos en la documentación del método.

Solicitar un token con Postman

  1. Cree una solicitud POST a https://YOUR_DOMAIN/oauth/token/.
  2. En Body, seleccione x-www-form-urlencoded.
  3. Agregue client_id, client_secret, grant_type y scope.
  4. Envíe la solicitud y verifique que la respuesta incluya token_type, expires_in, access_token y scope.

Ejemplo de respuesta:
{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "YOUR_ACCESS_TOKEN",
  "scope": "read"
}

Consumir la API con el access token

Envíe el token en la cabecera Authorization con el prefijo Bearer:
curl --request GET \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  'https://api.example.com/accounts/v1/accounts.json/'


Una respuesta HTTP 200 confirma que la solicitud fue aceptada. El contenido y código HTTP de la respuesta depende del método consultado.



Errores frecuentes

ResultadoCausa probableQué revisar
400Solicitud de token incompleta o mal formadaContent-Type, nombres de campos, grant_type y scope.
401Credencial ausente, inválida o vencidaAPI Key o cabecera Authorization; genere un token nuevo si expiró.
403La aplicación no tiene acceso o el scope no alcanzaScopes solicitados al obtener token.
404URL o versión incorrectasDominio, nombre de API, versión, ruta y barra final indicada en la documentación.

Buenas prácticas de seguridad

  • No publique Auth Keys, Client Secrets ni access tokens en documentación, capturas, repositorios o tickets.
  • No use Client Credentials directamente desde aplicaciones web o móviles donde el secreto pueda quedar expuesto.
  • Conserve las credenciales en un gestor de secretos o en variables de entorno protegidas.
  • Solicite el menor conjunto de scopes necesario y renueve el token cuando venza.
  • Rote o revoque una credencial de inmediato si sospecha que fue expuesta. 

Artículos relacionados