Actuar en nombre de una hija
Maneja cualquier empresa hija desde una sola master key con el header X-Active-Profile — resolución del perfil, el guard de propiedad y cómo los scopes se mantienen fijos.
Una vez que tienes empresas gestionadas bajo tu tenant
maestro, hay dos formas de actuar sobre una de ellas. Puedes emitir una API key
hija ligada a ella — útil cuando quieres una credencial
acotada a una sola empresa. O puedes seguir usando tu master key y elegir la
empresa objetivo por petición con el header X-Active-Profile. Así, una sola
master key opera sobre cualquier empresa de tu árbol, sin re-autenticarte ni
gestionar una key por NIF. Esta página cubre el header.
Pon en el header el id público (UUID v7) de la empresa hija sobre la que quieres
actuar. Funciona sobre cualquier endpoint — facturas, clientes, series y el
resto:
curl https://api.factuarea.com/v1/invoices \
-H "Authorization: Bearer fact_live_8KqW3pXnR2VbY7TcA9eFmN5z" \
-H "X-Active-Profile: 01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c"Cuando el header está presente y la empresa es tuya, toda la petición se
ejecuta sobre los datos de esa empresa hija: cada lectura se filtra a ella y cada
escritura cae sobre ella. La petición se resuelve al company_id de la empresa
hija antes del rate limit y la idempotencia, así que cada empresa tiene sus
propios buckets.
El header es opcional y aditivo. Omítelo y la petición opera sobre la empresa a la que pertenece tu key — exactamente como antes. Las integraciones existentes siguen funcionando sin cambios.
El header nunca amplía tu key. Sus scopes, tier y environment se
conservan intactos: una master key con solo invoices:read que apunta a una
empresa hija sigue sin poder hacer POST /v1/invoices ahí (403 insufficient_scope), y una key fact_test_ se mantiene en el sandbox sea cual
sea el perfil activo. Cambiar de perfil cambia sobre qué empresa actúas,
nunca qué tienes permitido hacer. La empresa hija hereda el plan y los
add-ons del maestro.
Resolución y errores
X-Active-Profile resuelve la empresa activa antes de que corra ningún handler:
| Header | Resultado |
|---|---|
| Ausente o vacío | La petición opera sobre la empresa a la que pertenece la key (no-op). |
El id de tu propia empresa maestra | Permitido — equivale a omitir el header. |
Una empresa hija que posees, active | La petición opera sobre esa empresa hija. |
Una empresa hija que posees, pero inactive | 403 company_inactive — reactívala primero. |
| No es un UUID v7 válido | 400 parameter_invalid_uuid, con param: "X-Active-Profile". |
| Una empresa que no posees (otro árbol, o inexistente) | 404 profile_not_found. |
El 404 es indistinguible tanto si la empresa pertenece a otro maestro como
si no existe — la API nunca revela que una empresa fuera de tu árbol existe:
{
"error": {
"type": "not_found_error",
"code": "profile_not_found",
"message": "El perfil de empresa indicado no existe o no pertenece a tu cuenta.",
"param": "X-Active-Profile"
}
}El 403 es distinto: la empresa sí es tuya, así que revelar que está
desactivada es legítimo — es la señal para
reactivarla antes de operar:
{
"error": {
"type": "authorization_error",
"code": "company_inactive",
"message": "Esta empresa está desactivada. Actívala para operar.",
"param": "X-Active-Profile"
}
}¿Cuál deberías usar?
X-Active-Profile y las API keys hijas resuelven
necesidades distintas y coexisten:
- Usa una key hija para entregar una credencial acotada a una integración ligada a una empresa — la credencial en sí queda ligada a esa empresa.
- Usa el header para manejar muchas empresas desde una sola master key — una credencial, empresa objetivo elegida por petición.
El header solo cambia la empresa activa. Nunca cambia los scopes de la key, y el
aislamiento entre maestros se aplica igual que al gestionar las
empresas: una empresa fuera de tu árbol nunca es
observable, devolviendo 404 en vez de 403.