Autenticación y scopes

Una sola API Key habilita toda la API. Lo que cambia entre superficies no es el mecanismo: son los scopes.

API Key

Cada request debe autenticarse con una API Key (prefijo ilk_). Podés enviarla de dos formas (si van ambas, gana Authorization):

Authorization: Bearer ilk_live_xxx

x-api-key: ilk_live_xxx

Si falta o es inválida/revocada/expirada, la API responde 401 con un mensaje genérico (no distingue el motivo, por seguridad).

Scopes (alcances)

La autorización es aditiva (ALL_OF): tu key debe tener todos los scopes que exige la superficie, el modelo, la fuente o el nivel involucrados.

Person Search

Scope	Para qué
person_search:read	Requerido para usar la búsqueda de personas.
person_search:advanced	Requerido además para el modelo PERSON_ADVANCED.
provider:arca	Requerido para incluir los payloads de ARCA en la respuesta.

• Si te falta person_search:read → 403.
• Si pedís PERSON_ADVANCED sin person_search:advanced → 403.
• Si te falta provider:arca, no es un error: la fuente ARCA simplemente se excluye de la respuesta, de forma silenciosa.

Fuentes

Scope	Para qué
sources:read	Requerido para el catálogo y para consultar cualquier fuente.
provider:igj	Requerido además para consultar IGJ.
provider:arca	Requerido además para consultar ARCA.
provider:bcra	Requerido además para consultar BCRA.
provider:informelegal	Requerido además para consultar InformeLegal.

Acá la fuente es la consulta: sin su scope la respuesta es 403, nunca un resultado vacío. El endpoint GET /api/v1/sources te dice, por fuente, si tu key está autorizada (authorized).

Validaciones

Scope	Para qué
utils:email:validate	Requerido para validar emails.
utils:phone:validate	Requerido para los niveles LOCAL y CHECKMOBI_VERIFY del teléfono.
utils:phone:mnp	Requerido para el nivel MNP (pago).
utils:phone:hlr	Requerido para el nivel HLR (pago).

Los scopes de los niveles pagos son independientes de utils:phone:validate: tener uno no implica el otro.

Dos maneras de negar, y por qué

Situación	Respuesta	Por qué
Falta el scope de la superficie o del modelo	403	Sin eso no hay consulta posible.
Falta el scope de una fuente en Person Search	200 sin esa dimensión	El resto del resultado sigue siendo útil y correcto.
Falta el scope de una fuente en la consulta directa	403	La fuente es la consulta: un 200 vacío sería engañoso.

Buenas prácticas

• Tratá la API Key como un secreto: no la pongas en URLs, logs ni en el código del frontend.
• Nunca envíes claves personales (CUIT/DNI) en la query string; van siempre en el cuerpo del POST.
• Rotá tu key si sospechás que se filtró (el equipo puede revocarla y emitir una nueva).

Ver también: Errores · Modelos · Fuentes.