Skip to main content

Authentication & tokens

Personal access tokens are the credential for everything outside the WriteMars app — the REST API and the MCP server both accept them. A token acts as you: it sees your workspaces and carries your roles in them.

Create a token​

  1. Open WriteMars and go to Profile → API Tokens (profile menu, bottom-left).
  2. Click New token.
  3. Fill in the form:
    • Label — what this token is for, e.g. Claude Code or CI pipeline. Labels are how you'll recognize tokens later when deciding what to revoke.
    • Workspace access — All my workspaces, or pin the token to a single workspace. A pinned token gets 403 everywhere else, which is the safer default for CI and third-party tools.
    • Expires — Never, or 30/90/365 days. Expired tokens stop working automatically.
  4. Click Create token.
  5. Copy the token now. This is the only time the plaintext (writemars_pat_...) is shown — WriteMars stores only a SHA-256 hash. If you lose it, revoke it and create a new one.

New tokens carry the writemars_pat_ prefix. Tokens issued earlier under the socle_pat_ prefix keep working — the API accepts both — so there's nothing to reissue.

The reveal screen also shows ready-to-copy connect commands for Claude Code and Cursor with your token already filled in — if that's what you came for, you're done.

Make your first API call​

curl -H "X-API-Key: writemars_pat_..." \
  https://api.writemars.com/api/workspaces/

You should get a JSON array of your workspaces. The Authorization: Bearer writemars_pat_... header works identically if you prefer it.

From here:

Token hygiene​

  • Treat tokens like passwords. Anyone holding one can act as you in WriteMars.
  • Revoke from Profile → API Tokens; revocation is immediate (the next request with that token gets 401).
  • Never put a token in a URL — URLs end up in logs. Headers only.
  • The Last used column on the tokens page tells you which tokens are actually in use (updated at most every few minutes).
  • One token per integration. When something only needs one workspace, scope it.
  • Token management requires a browser session. /api/tokens/ never accepts an API token — by design, a leaked token can't mint or revoke tokens.