Choosing a board

A credential reaches the boards it was ticked for — one or several. Every call except /v1/me is about exactly one of them, and says which in a header.

curl https://api.tylon.app/v1/board \
  -H "Authorization: Bearer $TYLON_SECRET" \
  -H "X-Tylon-Workspace: 84415731592203229"

Why a header, and why an id

A header because it belongs with the credential rather than with the request. The same value goes on every call your integration makes, and something that never varies has no business in a URL that does — it also keeps it out of the logs and browser histories that record paths. An id because a name is a thing somebody renames on a Tuesday, and a slug is a thing two organizations can share. Either one can turn a working integration into a silent one — or, worse, into one now reading a different board. An id cannot come to mean something else.

The MCP server does accept acme/product, and that is not an inconsistency. There a person is typing it and a model is reading the refusal. Here nobody is typing anything.

Finding the ids

/v1/me is the listing, and the one call that never asks you to choose.

curl https://api.tylon.app/v1/me -H "Authorization: Bearer $TYLON_SECRET"

{
  "clientId": "tyl_id_1yIrdcxW_gkz8XBY",
  "name": "the deploy script",
  "scopes": ["read"],
  "boards": [
    {
      "workspaceId": "84415731592203229",
      "organizationId": "84415731491539931",
      "role": "viewer"
    },
    {
      "workspaceId": "83729280714017040",
      "organizationId": "81904798345068545",
      "role": "member"
    }
  ],
  "answering": null
}

boards is exactly the set of ids the header will accept. answering is which board served the call — always null here, because this route answers with the list rather than out of it.

When you can leave it out

When the credential reaches exactly one board. Then there is no question to ask, and the header is optional. Leave it out with several and you get 400 with the ids:

{
  "message": "Say which workspace in the X-Tylon-Workspace header: 84415731592203229, 83729280714017040.",
  "error": "Bad Request",
  "statusCode": 400
}

The refusals

400

{ "message": "X-Tylon-Workspace takes a workspace id, not a name. This credential reaches 84415731592203229, 83729280714017040." }

Said plainly rather than answered as “no such board”, so a slug pasted in by habit does not read as a board that has gone missing.

400

{ "message": "This credential does not reach workspace 12345678901234567. It reaches 84415731592203229, 83729280714017040." }

Boards do not leak into each other

A projectId belonging to another board is 404, even when that board is one the same credential reaches. Card numbers are per board: /v1/cards/7 answers with card #7 of the board in your header, and never with another board’s.

Overview

Endpoints

Choosing a board

Why a header, and why an id

Finding the ids

When you can leave it out

The refusals

Boards do not leak into each other

​Why a header, and why an id

​Finding the ids

​When you can leave it out

​The refusals

​Boards do not leak into each other

Why a header, and why an id

Finding the ids

When you can leave it out

The refusals

Boards do not leak into each other