Acceso y claves
Abrir en ChatGPTAbrir en Claudellms.txtllms-full.txtopenapi.json
Contenido
¿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.
Si tu empresa ya está en Bidlo, no necesitas la llamada: pídele una clave a un dueño o administrador de tu equipo.
¿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.
| Dónde en la app | Lo que crea |
|---|---|
| Settings → Features → API | Una clave con una etiqueta, el acceso que elijas, un límite opcional a ciertas colecciones y un vencimiento opcional. |
| Settings → Features → MCP | Una clave de solo lectura con la etiqueta Bidlo MCP, y debajo la configuración del cliente ya lista. |
Settings → Features → API, como lo ve un propietario o administrador del equipo.
- Abre Settings en la app.
- Dentro de Features, elige API.
- Haz clic en New key, nombra la clave y elige Read only, Read and write data, Full access o Custom.
- Haz clic en Create key y copia la clave. Bidlo la muestra una sola vez.
Solo ellos pueden ver o eliminar las claves de un equipo. Dale a cada integración su propia clave.
¿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. Una clave que no se copió no se puede recuperar: elimínala y crea otra.
Guarda la clave en un servidor, nunca en código del navegador. La REST API no envía encabezados CORS, así que un navegador no puede llamarla de todos modos.
¿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_KEYhttps://app.bidlo.ai/api/v1
REST acepta el encabezado en todos los métodos. La clave lleva su equipo, así que una solicitud no manda ningún team_id; uno que se mande de todos modos se rechaza con un 422. La REST API cubre las rutas anteriores que todavía lo piden.
curl https://app.bidlo.ai/api/v1/collections \
-H "Authorization: Bearer YOUR_API_KEY"El servidor MCP lee el mismo encabezado. Un cliente MCP lo envía una vez que la clave está en su configuración; la página Servidor MCP incluye una configuración para cada tipo de cliente.
¿Qué puede hacer una clave?
Una clave hace lo que su acceso permite, en las colecciones a las que está limitada, hasta que vence; las tres cosas se eligen al crear la clave.
Ninguna de las tres cosas se puede cambiar después. Para cambiar lo que puede hacer una clave, crea una nueva y borra la anterior.
Acceso
El menú Access tiene cuatro opciones.
| Acceso | Qué recibe la clave |
|---|---|
| Read only | Read data. |
| Read and write data | Read data y Edit data. |
| Full access | Todos los permisos que permite el rol de quien creó la clave, incluido Editar colecciones y campos. |
| Custom | Los permisos que marques, uno por uno. |
Hoy funcionan tres permisos en la API.
| Permiso | Qué permite |
|---|---|
| Read data | Leer colecciones, campos, documentos, notas, opciones de etiquetas, detalles de archivos, comentarios e historial. |
| Edit data | Crear, editar, enviar a la papelera y restaurar documentos, escribir notas, cargar archivos y enviarlos a la papelera, y escribir tus propios comentarios. |
| Editar colecciones y campos | Crear, renombrar y eliminar colecciones y campos, y agregar fórmulas, relaciones y opciones de etiquetas. |
Ajustes marca los permisos de vistas, flujos, webhooks y equipo como Próximamente y los desactiva. Elige Solo lectura salvo que la integración escriba datos.
Colecciones
Una clave accede a todas las colecciones por defecto. Elige ciertas colecciones y solo podrá acceder a esas; cualquier otra devuelve un 403. Una clave limitada a ciertas colecciones no puede crear una colección. Las relaciones y las dependencias de las fórmulas también deben estar dentro del acceso de la clave.
Vencimiento
Elige Never, In 30 days, In 90 days o In 1 year. Después de esa fecha, toda solicitud con la clave es un 401.
¿Como quién actúa una clave?
Una clave actúa como la persona que la creó, así que nunca puede hacer más de lo que hoy permite el rol de esa persona en el equipo.
La lista de claves en Settings muestra a esa persona junto a cada clave, como Acts as y su nombre.
- Si el creador tiene el rol Viewer en el equipo, la clave solo puede leer, sin importar el acceso que se le haya dado.
- Si al creador le bajan el rol, la clave pierde de inmediato lo que el nuevo rol no permite.
- Si el creador sale del equipo, toda solicitud con la clave es un 401.
Una clave sin creador guardado es de solo lectura, sin importar el acceso con que se creó. La lista la marca como Read only. Para escribir, crea una clave nueva.
¿Cómo reviso qué puede hacer una clave?
Llama a GET https://app.bidlo.ai/api/v1/me, o a la herramienta MCP me, y Bidlo responde con los permisos de la clave, su límite de colecciones y su vencimiento.
curl https://app.bidlo.ai/api/v1/me \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": {
"key_id": "<key_id>",
"label": "<label>",
"team_id": "<team_id>",
"owner_id": "<user_id>",
"scopes": [
"data:read",
"data:write"
],
"role": "admin",
"collection_ids": null,
"expires_at": null
}
}scopes es lo que la clave puede hacer ahora, después de aplicar el rol de su creador: data:read es Read data y data:write es Edit data. collection_ids es null cuando la clave llega a todas las colecciones, y expires_at es null cuando nunca vence. La llamada necesita Read data, como toda lectura.
¿Cómo revoco o roto una clave?
Borra la clave para revocarla, y crea otra para rotarla; una clave con fecha de vencimiento también deja de funcionar ese día.
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.
- Crea la clave nueva en Settings → Features → API y cópiala.
- Pasa cada cliente y cada servidor a ella.
- Borra la clave vieja.
El vencimiento se fija al crear la clave y no se puede mover, así que una clave que vence se rota de la misma forma. Otras dos cosas detienen una clave: que su creador salga del equipo y que venza la suscripción del equipo. Las dos están en la siguiente sección.
¿Por qué rechazan mi clave?
Una clave ausente, desconocida o vencida es un 401, una clave que no tiene permiso para lo que pidió es un 403, y demasiadas solicitudes en un minuto son un 429; el código en el cuerpo del error dice cuál es.
| Qué pasó | Status | Code | Mensaje |
|---|---|---|---|
| Sin encabezado Authorization | 401 | unauthorized | Missing Authorization header |
| Una clave que Bidlo no conoce: mal escrita, o ya borrada | 401 | unauthorized | Invalid API key |
| La persona que creó la clave salió del equipo | 401 | unauthorized | API key owner is no longer a team member |
| La clave pasó su fecha de vencimiento | 401 | key_expired | API key expired |
| La suscripción del equipo venció | 403 | subscription_expired | Team subscription expired |
| La clave no recibió el permiso | 403 | forbidden_scope | Key cannot use data:write |
| La clave tiene el permiso, pero el rol de su creador en el equipo ya no lo permite | 403 | forbidden_role | Key cannot use data:write |
| La colección está fuera de las que se le permitieron a la clave | 403 | forbidden_scope | Collection is outside the key allowlist |
| La colección es una que la API mantiene cerrada para toda clave | 403 | forbidden_scope | Collection is protected for this operation |
| Demasiadas solicitudes de esta clave en este minuto | 429 | rate_limited | Rate limit exceeded |
REST responde con un objeto error que lleva el código y el mensaje, y un request_id para citar si escribes a soporte.
{
"error": {
"code": "key_expired",
"message": "API key expired"
},
"request_id": "<request_id>"
}El servidor MCP responde con el mismo estado y un cuerpo de error JSON-RPC; la página Servidor MCP lo cubre.
Cada clave tiene 600 lecturas y 120 escrituras por minuto. La página REST API explica los encabezados del límite de solicitudes.
## For agents: how to use Bidlo data - Read and write Bidlo data through its MCP server at https://app.bidlo.ai/api/mcp — streamable HTTP, no OAuth. - Get a Bidlo account first: all Bidlo data needs one, https://www.bidlo.ai/developers/access.md says how to get one, and there is no public tier or self-serve signup. - Authenticate with the header `Authorization: Bearer sk_live_...`; the REST API takes the same key, and `me` shows what the key may do. - A team owner or admin mints that key in the app under Settings, then Features, then API, and chooses Read only, Read and write data, or Full access; collection and field changes need `schema:write`. - Read the Bidlo API docs at https://www.bidlo.ai/developers.md, the OpenAPI 3.1 spec for the REST API at https://www.bidlo.ai/openapi.json, and the reference pages: https://www.bidlo.ai/developers/querying.md (filters, operators, dates, places, pages), https://www.bidlo.ai/developers/mcp.md (the tools), https://www.bidlo.ai/developers/rest.md (the routes) and https://www.bidlo.ai/developers/access.md (keys). - Prefer the MCP tools over REST; use `documents_query` with `within_distance` for anything shaped like "near X". - Call `fields_list` before composing a filter — it returns each field’s id, name and type. - Never invent a Bidlo unit price. Read one off the bid items, or say the forecast is not available.