Autenticación y llaves de API

Autentica cada petición con llaves sk_test_ y sk_live_: creación, alcances, rotación y buenas prácticas.

Toda petición al API se autentica con una llave de API. Las llaves pertenecen a una organización, tienen alcances (scopes) configurables y vienen en dos ambientes: prueba y producción.

Anatomía de una llave

sk_test_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345
│  │    │
│  │    └── 32 caracteres aleatorios
│  └── Ambiente: test (sandbox) o live (producción)
└── Prefijo: sk = secret key

Una llave sk_test_ nunca puede leer ni modificar datos de producción, ni al revés. El aislamiento es total. Consulta Modo de prueba.

Envía tu llave

Dos formas equivalentes; usa la que prefiera tu cliente HTTP:

curl https://api.sendit.mx/v1/shipments \
  -H "X-API-Key: sk_test_..."

curl https://api.sendit.mx/v1/shipments \
  -H "Authorization: Bearer sk_test_..."

Crea una llave

Desde el dashboard (Configuración → Llaves de API → Crear llave) o por API:

curl -X POST https://api.sendit.mx/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integración tienda en línea",
    "environment": "live",
    "scopes": ["shipments:write", "shipments:read", "rates:read", "labels:write", "tracking:read"]
  }'

Parámetros del cuerpo

La llave completa se muestra una sola vez en la respuesta. Si la pierdes, no hay forma de recuperarla: genera una nueva. En el dashboard identificas cada llave por su prefijo visible (sk_live_aBcD...).

Cada plan tiene un tope de llaves activas. Crear una de más devuelve 403 PLAN_LIMIT_REACHED. El conteo excluye las llaves en su ventana de rotación de 24 h. Ver planes y cuotas.

Limita el alcance de cada llave

Cada llave lleva una lista de alcances con el patrón recurso:acción. Una llave solo puede hacer lo que sus alcances permiten. Todo lo demás responde 403.

{
  "name": "Integración tienda en línea",
  "scopes": [
    "shipments:write",
    "shipments:read",
    "rates:read",
    "labels:write",
    "tracking:read"
  ]
}

Emite cada llave con el mínimo privilegio que necesita esa integración. La lista completa de alcances y su semántica está en Alcances.

Rota una llave

1. Genera una llave nueva con los mismos alcances.
2. Actualiza tu integración para usar la nueva.
3. Revoca la anterior.

Mantén ambas activas durante la transición y vigila el campo lastUsedAt de la llave vieja para confirmar que ya nadie la usa antes de revocarla.

Restringe por IP

Beta Esta función está en beta. Su comportamiento puede ajustarse antes de la versión final.

Opcionalmente, limita una llave a un rango de IPs con una lista CIDR. Una petición desde una IP fuera de la lista se rechaza aunque la llave sea válida. Úsalo en llaves de producción que solo deben usarse desde tus servidores.

Usuarios del dashboard

Quien inicia sesión en el dashboard se autentica con una sesión de usuario y opera bajo el rol que tiene en la organización:

Los roles aplican a personas; los alcances aplican a llaves. Para integraciones servidor a servidor usa siempre llaves de API.

Errores de autenticación