Build on Trama

Personal token

Scripts and server-side integrations should use a personal token. Create or replace it in SettingsAPI & MCP. The same token also works as a Bearer token on the MCP server, which splits it for you; the REST API only takes the two headers.

When X-Api-Key is present it is the only credential the API looks at: a wrong pair answers 401 even if a valid Authorization header is sent too.

E-mail login (JWT)

The web app signs in with a code sent by e-mail. Each step is a POST /login: first with the address, then with the address and the code.

# 1. Ask for a code (a 400 answer here means the e-mail was sent)
curl -X POST https://api.ontrama.com/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# 2. Exchange the 6-digit code for a JWT (201: {"user": {…}, "token": "…"})
curl -X POST https://api.ontrama.com/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "otp": "123456"}'

# 3. Use it
curl https://api.ontrama.com/me -H "Authorization: Bearer YOUR_JWT"

• Codes have 6 digits, last 10 minutes and work once. Only the latest code counts; five wrong tries lock it.
• Login is rate limited to 30 requests per IP and 10 per address every 15 minutes, answered with 429 and Retry-After.
• POST /logout ends every JWT issued to the account until then, on all devices. Personal tokens keep working.

OAuth 2.1

Trama is an OAuth 2.1 authorization server, built for MCP clients: dynamic client registration (RFC 7591), server metadata (RFC 8414), protected-resource metadata (RFC 9728) and the authorization code flow with PKCE (S256). Clients are public (token_endpoint_auth_method: none). Access tokens (lxt_at_…) last 7 days; refresh tokens (lxt_rt_…) rotate on every use. An MCP client does all of this on its own; the MCP guide walks through the flow.

Three scopes. A client that asks for none gets all three, and you see them on the consent page.

You can see and revoke the apps you connected in SettingsConnected apps.

Issue keys

Every task gets a key from its workspace's prefix and a running number, like ACME-42. Keys stay put when cards move between columns and boards of the workspace; moving a task to another workspace gives it a new one. Mentioning a key in a description or a comment links the two tasks as related, when you can edit the other board.

• Ordering. Cards in a column are ordered by a fractional sort_key. New and moved cards go to the end unless you pass insert_after_task_id.
• Priority. priority_none, priority_low, priority_medium, priority_high or priority_urgent. Anything else is a 422.
• Dates and milestones. start_at and due_at (start on or before due), and an optional milestone_id from /boards/{board_id}/milestones on the same board. They drive the board's planning view.

Sub-issues & relations

A task can have a parent (parent_id): same workspace, up to 8 levels deep, no cycles, no templates. Create children with POST …/tasks/{task_id}/sub_issues, sending name, a list of names, or existing_task_id to adopt an issue that already exists. Reorder them with PUT …/tasks/{id}/reorder_sub_issues.

Relations are related, blocks, blocked_by and duplicate, created with POST …/tasks/{task_id}/relations. When a blocking task is done, its blocks links turn into related. The other task has to be on a board you can edit.

# Break a task into sub-issues
curl https://api.ontrama.com/boards/41/tasks/7104/sub_issues \
  -H "X-Api-Key: $TRAMA_KEY" -H "X-Api-Secret: $TRAMA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"names": ["Draft the copy", "Review with legal"]}'

# Mark it as blocked by another issue (id or key)
curl https://api.ontrama.com/boards/41/tasks/7104/relations \
  -H "X-Api-Key: $TRAMA_KEY" -H "X-Api-Secret: $TRAMA_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"related_task_id": "ACME-7", "relation_type": "blocked_by"}'

Templates

A task with is_template: true stays out of the columns and is listed under templates in the board payload; it has no issue key. Create a task from it with template_id on POST /boards/{board_id}/tasks: the name, description, priority, labels and checklists are copied (items unchecked). Assignees, dates, comments and attachments are not.

Who can see what

• You can see a board if you are one of its members, an admin of its workspace, a workspace member and the board is visible to the workspace, or signed in at all when the board is public (by link). Everything inside a board you can see is readable.
• Editing needs a member, admin or owner role on the board, or workspace admin. Managing it (members, sharing, visibility, archive, delete) needs admin or owner.
• A board you can't see answers 404, not 403, so its existence doesn't leak.