WorkRight API Quickstart

In the WorkRight dashboard, go to Settings → API Tokens and create a token. Pick its capabilities (see the tiers below), then copy the raw token — it looks like wr_<32hex> and is shown once. WorkRight never stores it in readable form, so if you lose it, revoke and create a new one. Each token is bound to a single (tenant, user)pair and can never reach another company's data.

A token's capability tier decides what it may do. The REST API maps tiers to HTTP methods:

• read — allows GET requests only.
• write — allows GET, POST, PATCH and DELETE.
• admin — reserved for the most sensitive operations (e.g. destructive webhook ops).

On the MCP server the same token carries fine-grained capability strings (e.g. leave.view, accounting.journal), and a tool is only visible and callable if the token holds its required capability.

Send the token on the Authorization header of every request. The production base URL is api.workright.in; every endpoint sits under /api/v1/public/.

# List leave requests (role-filtered to the token owner's scope)
curl https://api.workright.in/api/v1/public/leave/requests \
  -H "Authorization: Bearer wr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A write example — create an outbound webhook (needs a write token):

curl -X POST https://api.workright.in/api/v1/public/webhooks \
  -H "Authorization: Bearer wr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "slack",
    "category": "leave.approved",
    "url": "https://hooks.slack.com/services/T000/B000/xxxx",
    "label": "Leave approvals → #hr"
  }'

Money values are returned in paise (1 INR = 100 paise) to avoid floating-point errors, so total_paise: 150000 means ₹1,500.00.

The API allows 60 requests per minute per token. Past that you get 429 Too Many Requests with a Retry-After: 60 header. Errors share one envelope:

{
  "error": "invalid_token",
  "message": "token not found or revoked"
}

• 401 — missing or invalid bearer token.
• 403— the token lacks the required capability, or the feature isn't enabled on the plan. Sensitive reads (the employee roster, which carries PII) additionally require an HR-admin owner (company_admin or hr_manager).
• 404 — resource not found. 429 — rate limited.

The same token works with the WorkRight MCP server, which runs over stdio and works with any MCP client (Claude Desktop, Claude Code, Cursor). Add it to your client's MCP config with the token in WR_MCP_API_TOKEN:

{
  "mcpServers": {
    "workright": {
      "command": "workright-mcp-server",
      "env": {
        "WR_MCP_API_TOKEN": "wr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

On startup the server validates the token, resolves your tenant and user, and exposes only the tools your capabilities allow. See all of them in the MCP tool catalog.

Most tools and endpoints are reads. Writes exist only where they are safe (create a draft invoice or bill, apply for leave, submit an expense, manage webhooks) and reuse the dashboard's own validation, role checks and audit log.

By design, the most dangerous, irreversible actions are never exposed to the API or an AI agent — they stay dashboard-only behind interactive step-up authentication:

• Locking a payroll run or accounting period (Companies Act 2013 §128 write-once, TOTP-gated).
• Computing a full-and-final settlement and closing an offboarding cycle.
• Hiring a candidate (the irreversible offer→employee step).
• POSH complaints — never readable or writable over the API; highest-confidentiality, DPDP-sensitive.