Autenticación

Cada solicitud se autentica con una clave de API. Envíela como token Bearer:

Authorization: Bearer gsk_live_xxx

Si un token Bearer resulta incómodo en su entorno, también se acepta el encabezado x-api-key: gsk_live_xxx. Sin clave, cualquier solicitud recibe 401 con title: invalid_key.

Formato de la clave

gsk_live_<id>_<secreto> o gsk_test_<id>_<secreto>. Una clave gsk_live hace trabajo real y se cobra. Una clave gsk_test funciona en el sandbox: las herramientas se simulan y no se cobra nada; con ella no se pueden cambiar inmuebles, leads ni otros datos reales. El tipo de clave se elige al crearla.

El secreto se muestra una vez, al crearla. GREM guarda solo su hash, así que una clave perdida no se puede recuperar: cree una nueva y revoque la anterior.

Gestión de claves

En el panel, API → Claves:

• Crear una clave con una etiqueta. La configuración avanzada permite elegir ámbitos y una caducidad en días. Sin elección, la clave recibe todos los ámbitos.
• Rotar: emitir un secreto nuevo; el anterior sigue funcionando 24 horas para que pueda cambiarlo en su integración.
• Revocar: la clave deja de funcionar de inmediato y para siempre.

El estado de la clave aparece en la lista: active, funciona; suspended, acceso a la API pausado por un administrador (reversible, la clave no se destruye); revoked, revocada. Una clave con caducidad deja de aceptarse una vez vencida (401).

Claves de agencia

El propietario o un gestor de una agencia puede emitir una clave en nombre de la agencia: cambie la lista de claves al ámbito de la agencia. Esa clave:

• ve los inmuebles y leads de la agencia, no los personales;
• puede tomar leads del pool común de la agencia y devolverlos (Leads);
• puede pasar inmuebles a la agencia y asignar un agente (Inmuebles).

Una clave puede vincularse a un agente: entonces actúa como ese agente, con sus permisos.

Ámbitos

Cada clave lleva un conjunto de ámbitos. Una llamada sin el ámbito necesario devuelve 403 con title: forbidden_scope. El ámbito que requiere cada operación figura en su descripción en /openapi.json (campo x-required-scope).

Sin ningún ámbito puede llamar a GET /ping, GET /me, GET /dictionaries, GET /objects, GET /voices, GET /tools/status y GET /works.

Qué clave es esta

curl https://developers.grem.capital/api/v1/me \
  -H "Authorization: Bearer gsk_live_xxx"

GET /me devuelve el id y el prefijo de la clave, a quién pertenece (subjectType: user o agency, subjectId, y agencyMemberId para una clave de agente), los ámbitos concedidos, los límites que se aplican a esta clave concreta (rateLimit.rpm por minuto y rateLimit.rpd por día) y la caducidad. El secreto nunca se devuelve. Gratis.

Seguridad

• Guarde las claves en variables de entorno del servidor o en un gestor de secretos.
• Use una clave distinta por integración, con solo los ámbitos que necesita: revocar una no afecta a las demás.
• Rote las claves periódicamente.
• Las solicitudes se aceptan solo por HTTPS.

Artículos relacionados

• Errores: 401 y 403 en detalle.
• Límites y cobro: qué significan rpm y rpd.