Access and keys

How do I get access?

A Bidlo account is required. Anyone can get one by booking a call at https://cal.com/matt-wolfe-yecrho/30min — Bidlo sets the team up, and a team owner or admin then mints the API key in Settings → Features → API. There is no public tier and no self-serve signup.

That one key works on the MCP server and on the REST API. It reaches the collections your team reads in the app, and nothing else. If your company is already on Bidlo, you do not need the call: ask whoever owns the team for a key.

Book a call

Who can create a key?

Only a team owner or admin can create an API key, in the Bidlo app under Settings → Features → API.

Two screens in the app mint the same kind of key.

A key belongs to the team, not to the person who made it, and it reads that one team. The REST API asks for a team_id on every request even so, and the key's own team is the one it reads; the REST API page has the parameter list.

Owners and admins are also the only people who can see the list of keys on a team or delete one. A team can hold more than one key, so a client can be given its own.

What does a key look like?

A key is the prefix sk_live_ followed by 48 hexadecimal characters, and Bidlo shows it once.

That is 56 characters in all. Bidlo keeps a hash of the key rather than the key, so it can check one and can never print one again. The list in Settings shows each key by its label and its last four characters, which is enough to tell two apart and not enough to use.

Copy the key when you create it and put it where it is going to live. A key that was not copied is not recoverable: delete it and make another.

How do I send the key?

Send it in an Authorization header on every request, as the word Bearer, a space, then the key; the MCP server and the REST API read the same header.

The header is the same line either way. YOUR_API_KEY stands for the key you minted.

Authorization: Bearer YOUR_API_KEY

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

REST takes the header on a GET or a POST. A team_id is required on every request, in the query string on a GET and in the body on a POST. Send your team's id; with a key the key's own team is the one that is read, so the value carries no weight.

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

The MCP server takes the same header on a JSON-RPC POST. A client has to ask for both content types in Accept and send Content-Type: application/json, or the request comes back 406 or 415 before the key is read.

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"
  }'

Most readers never write that by hand. An MCP client sends the header once the key is in its config, and the MCP server page has a config for each kind of client. There is no OAuth flow and nothing to register: the discovery paths a client probes answer 404 on purpose, so it falls through to the key it was given.

What is the difference between read and write?

Nothing today: a key carries a read or a write access level, but the MCP server and the REST API only read, so a write key reads what a read key reads.

The level is set when the key is made, and read is the default. There is no route on either one that creates, changes or deletes anything, and every tool on the MCP server is a read, so nothing looks at the level as a gate.

Pick read. The MCP screen does it for you.

How do I revoke or rotate a key?

Delete the key to revoke it, and create another one to rotate; a key has no expiry date, so deleting is the only way to retire one.

Deleting takes effect on the next request: that key stops being a key. To change keys without a gap, mint before you delete.

1. Create the new key under Settings → Features → API and copy it.
2. Move every client and every server over to it.
3. Delete the old key.

Nothing else retires a key on a clock. The one thing that stops every key on a team at once is the team's subscription lapsing, which is the 403 in the next section.

Why is my key rejected?

A missing, mistyped or deleted key is rejected with a 401, and a key on a team whose subscription has lapsed is rejected with a 403 over REST and a 401 over MCP.

REST answers with a JSON object carrying an error key.

{
  "error": "Invalid API key"
}

The MCP server answers 401 for all three, with a JSON-RPC error body.

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

Two answers look like a key problem and are not. A REST request with no team_id is a 400 reading team_id is required, whatever key it carries. A collection name REST does not know is a 404, and that check runs before the key is read at all. The REST API page lists both.

How should I store a key?

Keep it on a server, in an environment variable or a secret store, and out of browser code, shared documents and version control.

A key reads everything its team can read, so it is worth what the account is worth.

• Read it from the environment at run time rather than writing it into the code.
• Call Bidlo from a server. The REST API sends no CORS headers, so a page in a browser cannot read it anyway, and a key shipped to a browser is a key its visitors have.
• Keep it out of version control, tickets and chat. Every copy is somewhere it has to be deleted from later.
• Give each client its own key, so one can be retired without touching the rest.
• If a key is seen by anyone who should not have it, delete it and create another.

Where do I go next?

Read Querying data next for the query model the MCP server and the REST API share, then the page for the one you are calling.

• Querying data — collections, fields, filters, sorts and pages, in the shape both of them use.
• MCP server — the client configs, the five tools and the order to call them in.
• REST API — the one route, its parameters, its response and its errors.

Anything this page does not answer, mail support@bidlo.ai.