Vas a lograr obtener una clave de API y autenticar tu primera llamada con ella.

​
Cómo se obtiene una clave

Las claves de API no se autogestionan: las emite Mozart desde el panel de administración interno, a pedido de tu organización. Pedile a tu contacto en Mozart que te dé de alta una clave — queda registrada bajo Organización → API keys del cliente correspondiente.
La clave se muestra una sola vez, en el momento en que se crea. Mozart no puede volver a mostrártela después: si la perdés, hay que revocarla y emitir una nueva.

​
Formato

La clave siempre tiene la forma moz_<stage>_<43 caracteres>. El segmento <stage> identifica el entorno que la emitió (live en producción); el resto es el secreto propiamente dicho. Tratá la clave completa como una contraseña: no la pegues en código de cliente ni en un repositorio.

​
Cómo se usa

Cada request lleva la clave en el header Authorization, como un token Bearer:
Una clave inexistente, mal formada, revocada o expirada responde 401 unauthorized. Si la organización dueña de la clave no está activa (por ejemplo, suspendida), la respuesta es 403 organization_inactive — la clave en sí es válida, pero la cuenta no puede operar. El detalle del formato de error está en Paginación, errores y límites.

​
Alcance de una clave

Una clave da acceso de lectura a todas las carteras activas de tu organización — no hace falta elegir carteras al crearla. Si tu organización no tiene ninguna cartera activa, la clave funciona (GET /v1/me responde igual) pero cualquier lista devuelve vacía.

​
Scopes: lectura y escritura

Cada clave tiene uno o más scopes. Una clave nueva sale con read únicamente por defecto — alcanza para todos los endpoints GET. El scope write (necesario para POST /v1/payments y el flujo de carga de cartera) no es el default: pedilo explícitamente a tu contacto en Mozart al solicitar la clave, o al pedir que se lo agreguen a una que ya tenés.
read siempre está presente en la clave final, aunque no lo pidas: no existe una clave sólo de escritura.
Un request contra un endpoint de escritura con una clave sin el scope write responde 403 forbidden. Igual que la revocación, un cambio de scopes en una clave existente puede tardar hasta 60 segundos en hacerse efectivo, por la misma caché.

​
Revocación

Revocar una clave es inmediato del lado de Mozart, pero puede tardar hasta un minuto en dejar de funcionar en la práctica: las claves se verifican contra una caché de 60 segundos por motivos de performance. Planificá ese margen si estás rotando una clave comprometida.

​
Buenas prácticas

  • Nunca la incluyas en código que corre en un navegador o una app móvil — siempre desde tu backend.
  • Usá una clave distinta por sistema o integración, para poder revocar una sin afectar a las demás.
  • Rotá periódicamente: pedí una clave nueva, migrá tu integración, después revocá la vieja.

​
Siguiente paso

Con tu clave lista, seguí la Guía de inicio rápido para hacer tus primeras llamadas.