Tokens, CI and scripts

Use Sign in with Qaldy whenever the client can open a browser. Use a personal access token for CI, scripts and clients that cannot.

Make one#

In the console open Agents (https://app.qaldy.com/agents), or open the command palette and type "Connect an agent", then choose Access token. Pick read-only or read and write. The page puts the token into the snippet for your client, shows it once, and lists your tokens with when each was last used and a Revoke button.

Tokens made there expire in 30 days. You can also make one under Backend, then Keys. From a terminal, qaldy tokens create --name "GitHub Actions" --read-only --days 90 asks you to approve it in the browser and prints the token once. A token can never make another token.

A token:

• works in one workspace (the one it was made in), as one person, and never exceeds what that person may do;
• carries a read or a write scope. A read token is offered the read tools only;
• starts with qat_, is shown once, and is stored only as a keyed hash;
• is refused on anything that changes who has access, spends money or widens an app's reach (console_only, approval_needs_console).

Put it in a client#

Claude Code:

claude mcp add --transport http qaldy https://mcp.qaldy.com/mcp --header "Authorization: Bearer qat_…"

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "qaldy": {
      "url": "https://mcp.qaldy.com/mcp",
      "headers": { "Authorization": "Bearer qat_…" }
    }
  }
}

VS Code (.vscode/mcp.json); the token is asked for once and kept out of the file:

{
  "inputs": [
    { "type": "promptString", "id": "qaldy-token", "description": "Qaldy personal access token", "password": true }
  ],
  "servers": {
    "qaldy": {
      "type": "http",
      "url": "https://mcp.qaldy.com/mcp",
      "headers": { "Authorization": "Bearer ${input:qaldy-token}" }
    }
  }
}

Anything that sends HTTP can call the REST API with the same header, on the routes marked with a token scope in the API reference:

curl -H "Authorization: Bearer $QALDY_TOKEN" https://cloud-api.qaldy.com/v1/tokens/self

In CI#

Put the token in the job's secrets as QALDY_TOKEN. The command line reads it, and the audit log records the call as ci/…. Make it read-only unless the job must build, and give it a short life.

Ending access#

Revoke a token on the Agents page, or from the machine that holds it: qaldy logout revokes the token the CLI is using. A revoked token stops working at once at the API. The MCP server remembers a successful check for ten seconds at most.