REST API and OAuth

Can has a public REST API at https://api.can.randomfact.com. Everything the app can do to boards, tickets, tags, and comments, a script or integration can do too — with the caller's own identity and permissions.

API reference

What is available

All endpoints live under /v1 and are scoped by workspace slug:

  • Workspaces — list your memberships, read one workspace.
  • Boards — list, read, create, rename, and move to the trash.
  • Columns — list a board's columns.
  • Tickets — list, read, create, edit, move to the trash, bulk status change, reorder, semantic search, and slug-free resolution by key (GET /v1/tickets/LAUN-7 finds the ticket across all your workspaces).
  • Tags — full create / rename / recolor / delete.
  • Comments — full thread access including one-level replies and soft-delete.
  • Ticket links — list, add and remove a ticket's links (a GitHub pull request, or any other web page). Adding a URL that is already linked returns the existing link.

List endpoints paginate with pageSize (default 50, max 200) and an opaque cursor.

A ticket or board in the Trash does not exist as far as the rest of the API is concerned: reading or editing it answers 404, lists and search leave it out, and a bulk status change skips it. The trash endpoints reach it, with the same permissions as the app:

Operation Endpoint Who
Move a ticket to the trash DELETE .../boards/{key}/tickets/{ticketKey} Any member
List a board's trashed tickets GET .../boards/{key}/trash/tickets Any member
Restore a ticket POST .../boards/{key}/trash/tickets/{ticketKey}/restore Any member
Delete a trashed ticket forever DELETE .../boards/{key}/trash/tickets/{ticketKey} Admin
Move a board to the trash DELETE .../boards/{key} Admin
List the trashed boards GET .../trash/boards Admin
Restore a board POST .../trash/boards/{key}/restore Admin
Delete a trashed board forever DELETE .../trash/boards/{key} Admin

... is /v1/workspaces/{slug}. Trashing is undoable for 30 days; deleting forever is not, and answers 409 for an item that is not in the trash. A restored ticket goes back to its column, or to the first column of the same kind if that one is gone, at the bottom. Deleting a large board forever can take more than one call: until the board is gone, the answer is { "deleted": false } and the next call carries on.

Ticket responses come in two shapes. Reading one ticket — GET .../tickets/{key} or the slug-free GET /v1/tickets/{key} — returns everything: description, attachments, links, timestamps. Everything else returns a summary: id, boardId, columnId, title, assigneeId, agentAssigneeId, tagIds, commentCount, updatedAt. Creating or editing a ticket answers with that summary rather than echoing the body back; listing and searching add a descriptionPreview of the description's first 160 characters, and take view=full when you really do want every field of every ticket.

To change where tickets sit in a column, POST .../boards/{key}/tickets:reorder takes ticket keys and a position: "top", "bottom", { "before": "LAUN-4" } or { "after": "LAUN-4" }. The tickets land there together, in the order you list them. Add columnId (null for the backlog) to move them to that column in the same call; without it, before and after use the anchor ticket's column, and top and bottom keep each ticket in its own. The server works out the ranks, so you never send or read one, and the answer is just { "updated": <count> }. The anchor has to be a ticket in the destination column that is not one of those being moved; otherwise the answer is 400, with a code that says which. A move to another column is recorded in ticket activity like any status change; a reorder within a column is not recorded. Reordering changes a column's priority order, so someone who has sorted that column by another field in the app sees no change.

Authentication

The API accepts two kinds of credentials for interactive callers:

  • OAuth 2.0 access tokens — for integrations. Can runs a standard OAuth 2.0 / OpenID Connect server on the same hostname: authorization endpoint, token endpoint, and discovery document at /.well-known/openid-configuration. Public clients use PKCE; no client secret is required.
  • Firebase ID tokens — what the Can app itself uses; useful for quick scripts if you already have one.

Two long-lived credentials serve headless callers: personal access tokens (below), and workspace integration credentials — the rfi_can_… token another app's workspace uses to act as itself, described in Integrations.

New OAuth clients can be created two ways:

  • Dynamic client registration (POST /oauth/register, RFC 7591) — programmatic, no manual approval, rate-limited per IP.
  • The Authorize button in the Swagger UI walks you through a browser sign-in for trying out endpoints by hand.

Personal access tokens

For your own scripts, CI jobs, and headless tools there is a third credential: a personal access token (PAT). A PAT is a long-lived opaque token, prefixed rft_can_, that authenticates as you — same identity, same workspace memberships, same permissions as signing in. It is you acting as you: don't hand a PAT to an agent, a connector, or another person; those should keep using OAuth (or a workspace integration credential), so access is delegated and individually revocable.

  • Create one in workspace settings under API tokens (the tokens are personal, not workspace-scoped — the section just lives there). Give it a name and, optionally, an expiry date. The token is displayed exactly once; Can stores only a hash, so copy it immediately.

  • Use it as a standard bearer token:

    curl -H "Authorization: Bearer rft_can_..." \
      https://api.can.randomfact.com/v1/workspaces/my-team/boards
    
  • Revoke it from the same list at any time — revocation is instant, because every request looks the token up live. Expired tokens stop working the moment they expire and are eventually cleaned up automatically.

  • Auditability: changes made with a PAT are recorded in ticket activity with a via value of pat:<token name>, just as OAuth writes record the client name. The field rides along in board exports, and a ticket's History tab shows the name after the actor, as a muted via <token name>.

Permissions

Tokens identify a user, not a workspace. Every request is authorized against your live workspace membership at the moment of the call: if you are removed from a workspace or demoted from admin, the API reflects that on your very next request — no token revocation needed.

The API never reveals whether a workspace you cannot access exists; you get a 404 either way.

Auditability

Changes made through the API are recorded in ticket activity with a via value naming the caller (for example api:My Script for an OAuth client), so a board's export always distinguishes API writes from clicks in the app. Writes that reach the API through the hosted MCP server carry the same client name under an mcp: prefix, so you can tell an agent's edit from a script's. A ticket's History tab shows the name after the actor either way, as a muted via My Script.