Autenticación

La API de Toku soporta dos mecanismos de autenticación: API Key y OAuth M2M. Toda organización parte con API Key; OAuth se habilita a pedido y, al activarse, reemplaza a la API Key.

API Key

La API Key es el identificador único de tu Organización. La obtienes en el Backoffice, en Ajustes → Organización, e incluyes en el header x-api-key de cada llamada:

curl https://api.trytoku.com/invoices/in_K3a1P1_p_t5UHJHJXmpkQYmqXCHvXrNi \
  -H "x-api-key: TU_API_KEY"

Si tu organización tiene más de una Cuenta de cobro, cada una tiene además su propia llave, que viaja en el header x-account-key. Ver Headers y convenciones.

OAuth M2M

Para integraciones máquina-a-máquina, Toku soporta OAuth 2.0 con client credentials, usando Auth0 como proveedor de identidad. En vez de una llave estática, tu sistema pide un access token (JWT) de vida limitada y lo envía en el header Authorization:

1. Con tu client_id y client_secret, pides un token al endpoint de Auth0.
2. Auth0 valida las credenciales y devuelve un access_token (JWT) con expiración.
3. Llamas a api.trytoku.com con ese token como Bearer; la API lo valida y responde.

Frente a la API Key, gana en:

• Credenciales que expiran — un token filtrado deja de servir por sí solo.
• Autenticación centralizada — accesos, permisos y políticas se administran en Auth0.
• Estándar de la industria — OAuth 2.0 client credentials, validable por librerías y gateways existentes sin lógica propia.

1. Pide la habilitación

OAuth no viene activo por defecto: solicítalo a tu contraparte operativa en Toku. Al habilitarlo recibirás un client_id y un client_secret.

❗️

Activar OAuth deshabilita tu API Key

Los dos mecanismos no conviven: cuando OAuth queda activo, la autenticación por x-api-key deja de funcionar para tu organización. Migra todas tus llamadas en la misma ventana.

2. Pide un access token a Auth0

El token lo emite Auth0, no Toku, con una petición POST a su endpoint:

curl --request POST \
  --url https://toku-prod.us.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "TU_CLIENT_ID",
    "client_secret": "TU_CLIENT_SECRET",
    "audience": "https://toku-prod.us.auth0.com/api/v2/",
    "grant_type": "client_credentials"
  }'

La respuesta trae el access_token y su vigencia en expires_in. Reutilízalo mientras siga vigente y pide uno nuevo al vencer, en lugar de solicitar uno por request.

3. Llama a la API con el token

curl https://api.trytoku.com/invoices/in_K3a1P1_p_t5UHJHJXmpkQYmqXCHvXrNi \
  -H "Authorization: Bearer TU_ACCESS_TOKEN"

Un token ausente, vencido o inválido responde 401. Ver Errores y códigos de respuesta.