Autenticación JWT¶

Las APIs administrativas (tenant-mgmt, reporting-api, flow-engine admin endpoints) requieren JWT de Cognito. El widget y el endpoint público /v1/webchat/messages no: usan firma de tenant/widget.

Obtener un token (interactivo)¶

Para herramientas humanas, usa el hosted UI:

https://zen-dev-auth.auth.us-east-2.amazoncognito.com/oauth2/authorize
  ?response_type=code
  &client_id=4mr4vrvcvklm81m8gp2mb2eb72
  &redirect_uri=https://admin.dev.zen.zervizdev.com/callback
  &scope=openid+profile+email
  &code_challenge=<PKCE>
  &code_challenge_method=S256
  &state=<random>

Luego intercambia code por tokens:

curl -X POST https://zen-dev-auth.auth.us-east-2.amazoncognito.com/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'client_id=4mr4vrvcvklm81m8gp2mb2eb72' \
  -d 'code=...' \
  -d 'redirect_uri=https://admin.dev.zen.zervizdev.com/callback' \
  -d 'code_verifier=...'

Respuesta:

{
  "id_token":      "eyJ...",
  "access_token":  "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in":    3600,
  "token_type":    "Bearer"
}

Llamar a una API¶

curl https://1zwzz5s116.execute-api.us-east-2.amazonaws.com/v1/tenants \
  -H "Authorization: Bearer $ID_TOKEN"

El authorizer valida:

Firma JWKS de Cognito.
aud o client_id = 4mr4vrvcvklm81m8gp2mb2eb72.
exp no vencido.
Claim custom:tenant_id presente.

Y propaga al handler:

event.requestContext.authorizer.jwt.claims.sub → user id.
event.requestContext.authorizer.jwt.claims["custom:tenant_id"] → tenant.
event.requestContext.authorizer.jwt.claims["custom:role"] → rol.

Refresh¶

curl -X POST .../oauth2/token \
  -d 'grant_type=refresh_token' \
  -d 'client_id=4mr4vrvcvklm81m8gp2mb2eb72' \
  -d 'refresh_token=...'

Refresh tokens duran 30 días. ID/access tokens 1 hora.

Server-to-server (M2M)¶

Para integraciones backend, no uses el flow PKCE: pide a plataforma un app client confidential con client_credentials grant. Tendrás client_id + client_secret y un scope custom (zen/m2m).

curl -X POST .../oauth2/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d 'grant_type=client_credentials' \
  -d 'scope=zen/m2m'

M2M no propaga tenant_id automático: debes pasarlo en header x-tenant-id y el authorizer lo validará contra la lista de tenants autorizados para ese client.

Errores comunes¶

Código	Causa
`401 token_expired`	Refresca el access token.
`401 invalid_signature`	El token no fue emitido por nuestro user pool.
`403 missing_tenant_claim`	Usuario no tiene `custom:tenant_id`.
`403 insufficient_role`	Endpoint requiere rol superior.