Autenticación

Toda llamada de la API lleva la clave en el encabezado Authorization, en formato Bearer:

Authorization: Bearer fh_live_su_clave

Esa es la única forma aceptada. Una clave en un parámetro de consulta no se lee, porque una dirección con la clave dentro se filtra en los registros del proxy, en el historial del navegador y en el encabezado Referer.

Formato de la clave

fh_live_ + 43 caracteres de cuerpo + 6 de verificación

Son 57 caracteres en total. Ejemplo de lo que el panel muestra en la lista de claves: fh_live_7Qx4Kd, los primeros 14 caracteres. Es ese fragmento el que GET /public/v1/me devuelve en key.prefix, y es por él que usted sabe qué clave está en uso sin tener la clave entera.

Los últimos 6 caracteres son un verificador calculado a partir del resto. La API usa el verificador para rechazar una clave mal escrita sin ir a la base de datos.

El verificador también deja el formato fácil de buscar: una regla que reconozca fh_live_ seguido de 43 caracteres de cuerpo y 6 de verificación casi no se equivoca. Esa regla la configura usted, en el escaneo de secretos de su proveedor de git o en su propia línea de integración. Ningún proveedor reconoce este formato por su cuenta.

El prefijo fh_test_ queda reservado y nunca se emite. No hay clave de prueba porque no hay entorno de prueba.

Las claves emitidas en la primera versión de la API, sin los 6 caracteres de verificación, siguen siendo válidas.

La clave se muestra una sola vez

El servidor guarda solo un hash SHA-256 de la clave. Ni el soporte puede leer una clave ya creada. Si la pierde, rótela o cree otra.

Idioma de los mensajes

El encabezado Accept-Language elige el idioma del campo message del error. Se aceptan pt-BR (predeterminado), en y es, y se respeta el peso q. El campo code es siempre el mismo, en inglés: programe por él.

Todo rechazo de autenticación responde lo mismo

Cuando la API no acepta la clave, la respuesta es siempre esta, con HTTP 401:

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "Clave de API inválida, revocada o vencida.",
    "request_id": "0a8c1f2e-3b4d-4c5f-9a6b-7c8d9e0f1a2b",
    "doc_url": "https://docs.fatureihoje.com/es/errors#api_key_invalid"
  }
}

Es igual para todos estos casos:

• encabezado Authorization ausente o fuera del formato Bearer;
• clave con formato inválido, o con el verificador equivocado;
• clave que no existe;
• clave revocada;
• clave vencida;
• clave cuyo miembro fue suspendido, eliminado o tuvo el acceso desactivado;
• empresa inactiva;
• IP de origen fuera de la lista de IPs permitidas de la clave.

Esto es a propósito. Una respuesta distinta por motivo le diría a quien prueba claves al azar cuándo acertó una clave real y solo erró la IP. El costo es suyo, a la hora de depurar, y el resto de esta página existe para compensarlo.

Cómo descubrir el motivo

La respuesta no lo dice, pero el panel sí. Revise en este orden:

1. El encabezado. Authorization: Bearer <clave>, un solo espacio, sin comillas alrededor de la clave.
2. La clave. Copiada entera, sin espacio ni salto de línea al final. Compare los primeros 14 caracteres con el prefijo que muestra el panel.
3. El estado de la clave. El panel marca cada clave como Activa, En rotación, Vencida o Revocada.
4. La lista de IPs. Si la clave tiene lista, la IP de salida de su servidor tiene que estar en ella.
5. La dirección. Solo api.fatureihoje.com responde /public/v1. El host del panel devuelve 404.
6. El registro de uso. En el menú de la clave, en Ver uso. Muestra las llamadas de los últimos 30 días con fecha, método, ruta, estado, duración, IP y request_id. Una llamada rechazada entra en el registro cuando la API reconoce de qué clave se trata: clave revocada, vencida, rotada, miembro suspendido, usuario desactivado o IP fuera de la lista. Así es como usted descubre tanto la IP equivocada como una clave suya usada desde un lugar donde no debería estar.

Los dos del medio son los menos obvios, y por eso merecen el aviso: suspender a un miembro del equipo o desactivar su usuario tumba la integración que representa la clave de él, sin ninguna otra señal. Si una integración se detuvo el mismo día en que alguien salió del equipo, casi siempre es eso.

Dos rechazos no generan ninguna línea: un token que no es de ninguna clave, porque no hay empresa a la cual atribuir el intento, y una empresa inactiva, porque entonces el panel entero está bloqueado y el problema no es la clave. Si no aparece nada en Ver uso, empiece revisando esas dos.

Guarde el request_id

Toda respuesta trae el encabezado Request-Id, y el cuerpo del error repite el valor en request_id. Es por él que el soporte encuentra la llamada.

cURL

curl -i https://api.fatureihoje.com/public/v1/me \
  -H "Authorization: Bearer $FH_API_KEY"

-i imprime los encabezados de la respuesta junto con el cuerpo.

Node.js

request-id.mjs

const res = await fetch('https://api.fatureihoje.com/public/v1/me', {
  headers: { Authorization: `Bearer ${process.env.FH_API_KEY}` },
});

console.log(res.status, res.headers.get('request-id'));

PHP

request-id.php

<?php

$requestId = null;

$ch = curl_init('https://api.fatureihoje.com/public/v1/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('FH_API_KEY')],
    CURLOPT_HEADERFUNCTION => function ($ch, $header) use (&$requestId) {
        if (stripos($header, 'request-id:') === 0) {
            $requestId = trim(substr($header, strlen('request-id:')));
        }

        return strlen($header);
    },
]);

curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

echo $status, ' ', $requestId, PHP_EOL;

Python

request-id.py

import os
import urllib.error
import urllib.request

request = urllib.request.Request(
    "https://api.fatureihoje.com/public/v1/me",
    headers={"Authorization": f"Bearer {os.environ['FH_API_KEY']}"},
)

try:
    with urllib.request.urlopen(request) as response:
        print(response.status, response.headers["Request-Id"])
except urllib.error.HTTPError as failure:
    print(failure.code, failure.headers["Request-Id"])

No repita la llamada en un bucle cerrado

La API cuenta los fallos de autenticación por IP de origen. Pasando de 60 fallos por minuto, las llamadas siguientes de esa IP reciben 429 con el encabezado Retry-After, incluso con la clave correcta. Quien usa la clave correcta nunca gasta ese presupuesto.

Al recibir un 401, pare y corrija la configuración. Repetir la misma llamada equivocada solo retrasa la solución.

IPs permitidas

Cada clave acepta una lista de hasta 20 direcciones o rangos. Una lista vacía acepta cualquier IP.

Formatos aceptados, IPv4 e IPv6:

198.51.100.7
198.51.100.0/24
2001:db8::1
2001:db8::/32

Una dirección suelta vale como la máquina exacta (/32 en IPv4, /128 en IPv6).

La máscara se aplica al guardar. Si usted escribe 203.0.113.5/24, la entrada se guarda como 203.0.113.0/24, porque eso es lo que el rango significa. El panel muestra el valor ya normalizado: lo que está en la pantalla es exactamente lo que vale.

Una entrada inválida no se acepta ni se descarta en silencio: el panel rechaza el formulario. Descartarla en silencio podría vaciar la lista, y una lista vacía permite cualquier IP.

Una llamada desde una IP fuera de la lista recibe el mismo 401 de clave inválida, y el intento aparece en Ver uso con la IP que llegó.

El servidor en la nube cambia de IP

Un servidor gestionado, una función sin servidor y un contenedor con escalado automático suelen salir por una IP que cambia sin aviso. Cuando eso pasa, la integración entera cae con 401. O usted fija la IP de salida (IP dedicada, NAT gateway, proxy propio), o no usa la lista de IPs.

Vencimiento

En la creación usted elige entre no vence, 30 días, 90 días o 1 año. Después de esa fecha la clave responde 401 como cualquier clave inválida. Una clave con plazo reduce el daño si algún día se filtra.

Rotación

Rotar genera una clave nueva con el mismo nombre, los mismos permisos, el mismo miembro, la misma lista de IPs y la misma fecha de vencimiento, y deja la anterior con los días contados.

En el panel: menú de la clave, Rotar. Usted elige por cuánto tiempo la anterior sigue funcionando: detener ahora, 1 hora o 24 horas. En ese período las dos claves responden, y eso es lo que permite cambiar el secreto en sus sistemas sin cortar la integración.

Paso a paso:

1. Rote eligiendo el período de convivencia.
2. Copie la clave nueva, que también se muestra una sola vez.
3. Cambie el secreto en sus sistemas y haga un GET /public/v1/me con la clave nueva.
4. Revoque la anterior apenas lo confirme. No hace falta esperar a que termine el período.

Mientras la anterior sigue viva, el panel la marca como En rotación.

Cuatro detalles que suelen sorprender:

• La clave nueva hereda la fecha de vencimiento de la anterior. Rotar una clave que vence la semana que viene devuelve una clave que también vence la semana que viene. La rotación cambia el secreto, no renueva el plazo: para ganar plazo, cree una clave nueva.
• Durante la convivencia las dos claves cuentan en la cuota de claves activas del plan. La rotación en sí no se bloquea por eso, pero crear una clave más sí, hasta que la anterior muera.
• Una clave anterior ya rotada no se puede rotar de nuevo. Quien rota dos veces rota la clave nueva.
• En la clave anterior, una fecha de vencimiento anterior al fin de la convivencia vence sobre la convivencia: muere en esa fecha, no al final del período elegido.

Revocación

Revocar en el panel termina la clave en el acto. La llamada siguiente con ella recibe 401. No hay deshacer ni período de gracia: si la clave se filtró, esto es lo primero que se hace.

Los OWNER y ADMIN de la empresa reciben un correo cuando una clave se crea, se rota o se revoca.

Próximo paso

• Permisos: qué puede hacer la clave una vez autenticada.
• Referencia: las rutas publicadas, campo por campo.