Acceso y claves

¿Cómo consigo acceso?

Se necesita una cuenta de Bidlo. Cualquiera puede conseguir una agendando una llamada en https://cal.com/matt-wolfe-yecrho/30min — Bidlo prepara el equipo, y luego un dueño o administrador del equipo crea la clave de API en Settings → Features → API. No hay un plan público ni se puede abrir una cuenta por cuenta propia.

Esa misma clave sirve en el servidor MCP y en la REST API. Llega a las colecciones que tu equipo lee en la app, y a nada más. Si tu empresa ya usa Bidlo, no necesitas la llamada: pídele una clave a quien sea dueño del equipo.

Agenda una llamada

¿Quién puede crear una clave?

Solo un dueño o administrador del equipo puede crear una clave de API, en la app de Bidlo en Settings → Features → API.

Dos pantallas de la app crean el mismo tipo de clave.

Una clave es del equipo, no de la persona que la creó, y lee ese único equipo. La REST API pide un team_id en cada solicitud de todos modos, y el equipo de la propia clave es el que se lee; la página REST API tiene la lista de parámetros.

Los dueños y administradores también son los únicos que pueden ver la lista de claves de un equipo o borrar una. Un equipo puede tener más de una clave, así que a cada cliente se le puede dar la suya.

¿Cómo se ve una clave?

Una clave es el prefijo sk_live_ seguido de 48 caracteres hexadecimales, y Bidlo la muestra una sola vez.

Son 56 caracteres en total. Bidlo guarda un hash de la clave y no la clave, así que puede verificarla y nunca puede volver a mostrarla. La lista en Settings muestra cada clave por su etiqueta y sus últimos cuatro caracteres, lo justo para distinguir dos y no lo suficiente para usarla.

Copia la clave cuando la crees y ponla donde va a vivir. Una clave que no se copió no se puede recuperar: bórrala y crea otra.

¿Cómo mando la clave?

Mándala en un encabezado Authorization en cada solicitud: la palabra Bearer, un espacio y luego la clave; el servidor MCP y la REST API leen el mismo encabezado.

El encabezado es la misma línea en los dos casos. YOUR_API_KEY representa la clave que creaste.

Authorization: Bearer YOUR_API_KEY

https://lite.bidlo.ai/api/v1/<collection_id>

REST acepta el encabezado en un GET or a POST. Un team_id es obligatorio en cada solicitud, en la cadena de consulta en un GET y en el cuerpo en un POST. Manda el id de tu equipo; con una clave se lee el equipo de la propia clave, así que el valor no cuenta.

curl -X POST https://lite.bidlo.ai/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "<team_id>",
    "limit": 5
  }'

https://lite.bidlo.ai/api/mcp

El servidor MCP acepta el mismo encabezado en un JSON-RPC POST. Un cliente tiene que pedir los dos tipos de contenido en Accept y manda Content-Type: application/json, o la solicitud regresa 406 o 415 antes de que se lea la clave.

curl -X POST https://lite.bidlo.ai/api/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Casi nadie escribe eso a mano. Un cliente MCP manda el encabezado en cuanto la clave está en su configuración, y el Servidor MCP tiene una configuración para cada tipo de cliente. No hay flujo OAuth ni nada que dar de alta: las rutas de descubrimiento que prueba un cliente responden 404 a propósito, así que pasa a usar la clave que recibió.

¿Cuál es la diferencia entre lectura y escritura?

Nada hoy: una clave lleva un nivel de acceso de lectura o de escritura, pero el servidor MCP y la REST API solo leen, así que una clave de escritura lee lo mismo que una de lectura.

El nivel se define cuando se crea la clave, y lectura es el predeterminado. Ninguna de las dos tiene una ruta que cree, cambie o borre algo, y cada herramienta del servidor MCP es de lectura, así que nada usa el nivel como control.

Elige lectura. La pantalla de MCP lo hace por ti.

¿Cómo revoco o roto una clave?

Borra la clave para revocarla, y crea otra para rotarla; una clave no tiene fecha de vencimiento, así que borrarla es la única forma de retirarla.

Borrarla surte efecto en la siguiente solicitud: esa clave deja de ser una clave. Para cambiar de clave sin interrupción, crea la nueva antes de borrar la vieja.

1. Crea la clave nueva en Settings → Features → API y cópiala.
2. Pasa cada cliente y cada servidor a ella.
3. Borra la clave vieja.

Nada más retira una clave por tiempo. Lo único que detiene todas las claves de un equipo a la vez es que se venza la suscripción del equipo, que es el 403 de la siguiente sección.

¿Por qué rechazan mi clave?

Una clave ausente, mal escrita o borrada se rechaza con un 401, y una clave de un equipo con la suscripción vencida se rechaza con un 403 en REST y un 401 en MCP.

REST responde con un objeto JSON que trae error como clave.

{
  "error": "Invalid API key"
}

El servidor MCP responde 401 en los tres casos, con un cuerpo de error JSON-RPC.

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized: Invalid API key"
  },
  "id": null
}

Dos respuestas parecen un problema de clave y no lo son. Una solicitud REST sin team_id es un 400 que dice team_id is required, sea cual sea la clave que lleve. Un nombre de colección que REST no conoce devuelve un 404, y esa revisión corre antes de que se lea la clave. El REST API lista los dos.

¿Cómo debo guardar una clave?

Guárdala en un servidor, en una variable de entorno o en un almacén de secretos, y fuera del código del navegador, de los documentos compartidos y del control de versiones.

Una clave lee todo lo que su equipo puede leer, así que vale lo mismo que la cuenta.

• Léela del entorno al momento de correr, en vez de escribirla en el código.
• Llama a Bidlo desde un servidor. La REST API no manda encabezados CORS, así que de todos modos una página en el navegador no puede leerla, y una clave que llega al navegador es una clave que tienen sus visitantes.
• Mantenla fuera del control de versiones, de los tickets y del chat. Cada copia es un lugar más del que habrá que borrarla después.
• Dale a cada cliente su propia clave, para poder retirar una sin tocar las demás.
• Si alguien que no debería tenerla ve una clave, bórrala y crea otra.

¿A dónde voy después?

Lee a continuación Consultar datos para el modelo de consulta que comparten el servidor MCP y la REST API, y luego la página de la que vayas a llamar.

• Consultar datos — colecciones, campos, filtros, orden y páginas, en la forma que usan los dos.
• Servidor MCP — las configuraciones de cliente, las cinco herramientas y el orden en que se llaman.
• REST API — la única ruta, sus parámetros, su respuesta y sus errores.

Lo que esta página no responda, escribe a support@bidlo.ai.