Cuenta: tu clave y tu consumo

Cuenta

Las rutas de la cuenta, en /v1. /v1/me es lo primero que conviene llamar al integrar Normatia: si responde, la clave funciona.

Endpoint	Método	Descripción
`/v1/me`	GET	La clave, su organización, sus límites y el cupo que queda
`/v1/usage`	GET	Las llamadas y los créditos de la organización entre dos fechas
`/v1/keys`	GET	Tus claves en la organización de la clave, activas y revocadas
`/v1/keys/{key_id}`	DELETE	Revocar una de tus claves

Ninguna consume cuota: pertenecen al grupo de datos (60 peticiones por minuto). Responden con cualquier permiso y con una clave de prueba. Los errores van en el formato de /v1, descrito en Errores.

curl https://api.normatia.com/v1/me \
  -H "Authorization: Bearer $NORMATIA_API_KEY"

La clave y su organización

GET /v1/me

{
  "key": {
    "id": "8d1f0c3a-2b4e-4f6a-9c7d-1e2f3a4b5c6d",
    "mode": "live",
    "name": "Integración catastro",
    "hint": "a3f9",
    "scopes": ["data", "ask", "mcp"],
    "created_at": "2026-11-01T09:12:44Z",
    "last_used_at": "2026-11-01T10:02:13Z"
  },
  "user": {
    "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
    "email": "equipo@ejemplo.es"
  },
  "organization": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Ejemplo Datos S.L.",
    "plan": "team",
    "api_enabled": true,
    "mcp_enabled": false
  },
  "rate_limits": {
    "data_per_minute": 60,
    "intelligence_per_minute": 60,
    "mcp_per_minute": 60
  },
  "quota": {
    "unlimited": true,
    "remaining": null,
    "resets_at": "2026-12-01T00:00:00Z"
  }
}

Campo	Qué es
`key`	La clave con la que llamas. `hint` son sus últimos caracteres, los que ves en Mi cuenta > Claves API
`key.mode`	`live`, la de siempre, o `test`, una clave de prueba
`key.scopes`	Sus permisos: `data`, `ask` y `mcp`. Una de prueba, solo `data`
`organization`	La organización de la clave, la que da el acceso y a la que se cuenta el consumo. `null` si ya no eres miembro de ella
`rate_limits`	Peticiones por minuto de cada grupo de rutas. Con una clave de prueba, 30 de datos y 0 en los demás
`quota`	Las consultas que quedan este mes. Sin tope, `unlimited` es `true` y `remaining`, `null`

Consumo

GET /v1/usage

Parámetro	Tipo	Descripción
`from`	fecha, opcional	Primer día (`AAAA-MM-DD`). Por defecto, el 1 del mes en curso
`to`	fecha, opcional	Último día, incluido. Por defecto, hoy

Las fechas son en UTC. Como mucho, 92 días por petición.

curl "https://api.normatia.com/v1/usage?from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer $NORMATIA_API_KEY"

{
  "scope": "organization",
  "organization_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "from": "2026-11-01",
  "to": "2026-11-30",
  "totals": { "calls": 1284, "credits": 37, "errors": 12 },
  "by_endpoint": [
    { "endpoint": "/api/v1/codes/search", "calls": 902, "credits": 0, "errors": 3 },
    { "endpoint": "/api/v2/ask", "calls": 37, "credits": 37, "errors": 1 }
  ],
  "by_day": [
    { "date": "2026-11-01", "calls": 211, "credits": 6, "errors": 0 }
  ],
  "this_key": { "calls": 640, "credits": 20, "errors": 4 },
  "quota": { "unlimited": true, "remaining": null, "resets_at": "2026-12-01T00:00:00Z" }
}

Campo	Qué es
`scope`	`organization`: las cifras son de todas las claves de la organización. `key`: solo de esta clave
`totals`	Llamadas, créditos y llamadas con error (estado 4xx o 5xx) del periodo
`by_endpoint`	Lo mismo por ruta. En el servidor MCP, cada herramienta aparece como `/mcp/` y su nombre (`/mcp/get_parcel`, `/mcp/ask`), y el resto de peticiones al servidor (conectar, listar las herramientas), como `/mcp`
`by_day`	Lo mismo por día. Los días sin llamadas no aparecen
`this_key`	La parte de la clave con la que llamas

Tus claves

GET /v1/keys

Las claves del usuario de la clave en su organización, activas y revocadas, la más reciente primero. Las de otros miembros y las de tus otras organizaciones no aparecen. Normatia solo guarda una huella de cada clave, así que la lista no trae la clave completa.

{
  "keys": [
    {
      "id": "8d1f0c3a-2b4e-4f6a-9c7d-1e2f3a4b5c6d",
      "mode": "live",
      "name": "Integración catastro",
      "hint": "a3f9",
      "scopes": ["data", "ask", "mcp"],
      "status": "active",
      "created_at": "2026-11-01T09:12:44Z",
      "last_used_at": "2026-11-01T10:02:13Z",
      "revoked_at": null,
      "current": true
    }
  ]
}

Campo	Qué es
`mode`	`live` o `test` (una clave de prueba)
`scopes`	Sus permisos. Una de prueba, solo `data`
`status`	`active` o `revoked`
`current`	`true` en la clave con la que haces la petición

Revocar una clave

DELETE /v1/keys/{key_id}

Revoca una de tus claves activas en la organización de la clave, también la que hace la petición. Sirve para cortar una clave filtrada sin pasar por la web. Responde 204, sin cuerpo.

Deja de funcionar en menos de un minuto, en todas las rutas y en el servidor MCP.
No se puede deshacer: para seguir, crea otra en Mi cuenta > Claves API.
Una clave de prueba o con permisos limitados solo puede revocarse a sí misma. Con otro key_id responde 403 insufficient_scope.
Una clave de otro miembro, de otra organización, ya revocada o que no existe responde igual: 404 key_not_found.

curl -X DELETE https://api.normatia.com/v1/keys/8d1f0c3a-2b4e-4f6a-9c7d-1e2f3a4b5c6d \
  -H "Authorization: Bearer $NORMATIA_API_KEY"

Errores

Estado	`code`	Cuándo
422	`invalid_date_range`	`to` es anterior a `from`
422	`date_range_too_long`	El periodo pasa de 92 días
422	`validation_error`	Una fecha no tiene el formato `AAAA-MM-DD`
403	`insufficient_scope`	Una clave de prueba o con permisos limitados intenta revocar otra clave
404	`key_not_found`	No hay ninguna clave activa tuya con ese id en la organización

Más los de autenticación, en Errores.