Skip to content
wrktr docs

API authentication

The API is at https://api.wrktr.com, and every path starts with /api. The CLI, the daemon and the web app all use it; the API reference lists every endpoint, generated from the same contract the API is served from.

Personal access tokens

Section titled “Personal access tokens”

Send a personal access token as a bearer token:

Terminal window
curl -H "Authorization: Bearer $WRKTR_TOKEN" https://api.wrktr.com/api/me

Personal access tokens start with wrktr_. A token acts as the person who created it, with their access to their organizations’ projects.

Making one. A token can’t create tokens: only a person signed in to the web app can approve a new one. The CLI does it for you:

Terminal window
wrktr token create --name ci          # opens the browser to approve it, then prints the token once

wrktr login makes one the same way, for the CLI on your machine (saved in ~/.wrktr/config.json). A token can have an expiry, in days, or none.

Managing them. wrktr token ls lists your tokens: name, prefix (the first 12 characters), when each was created and last used, and when it expires. Never the values. wrktr token revoke <id> revokes one, and whatever uses it stops working at once. The same is in the API, under Account.

Without a token

Section titled “Without a token”

Reading a public project needs no token: its code, history, branches, reviews, CI and environments are open to anyone. Those endpoints accept a token but don’t require one, and a private project’s still answer only its organization’s members. GET /api/explore/projects lists public projects across every organization, and GET /api/health says whether the API is up.

A token that’s missing where one is required, or is invalid, expired or revoked, gets 401 with {"_tag": "Unauthorized", "message": "..."}.

Errors

Section titled “Errors”

Errors are JSON with a _tag naming the error, and the fields that say what’s wrong. For example, a project that doesn’t exist, or that you can’t see:

{ "_tag": "ProjectNotFound", "project": "acme/api" }

Each endpoint in the API reference lists the errors it can return, with their status codes.

Git

Section titled “Git”

The git remote takes short-lived tokens rather than your personal access token. Mint a git token for a project, or let wrktr credential do it: wrktr init and wrktr clone set it up as git’s credential helper for the remote, so plain git pull and git push work.