Skip to main content
Back to Home

API / CLI / MCP Guide

Connect Warrantee with ERP, ecommerce, scripts, internal systems, and agent workflows

Sign in to generate a keyOnboard as seller

Complete integration guide

Every production integration starts from a logged-in Warrantee account. Generate a scoped token in Settings, store it as a secret, then use it from REST API calls, CLI scripts, or MCP-aware agents.

  1. 1Sign in or create a Warrantee account.
  2. 2Open Settings > API / CLI / MCP.
  3. 3Generate a scoped integration token and copy it once.
  4. 4Store it in a secret manager or environment variable.
  5. 5Use the token as x-api-key for API, CLI, or agent requests.
  6. 6Monitor usage, rotate keys, and revoke unused tokens.

Base URL

https://warrantee.io/api/v1

Authentication

API access is limited to registered Warrantee users. For ERP, ecommerce, or server-to-server integrations, do not store a Warrantee username or password in the external system. Sign in once to Warrantee, create a dedicated integration token, then send that token as x-api-key.

No shared usernames or passwords

The person setting up the integration signs into Warrantee only to create, view, revoke, or rotate integration tokens. Do not use your login email or password in API, CLI, or MCP integrations. The connected system should store only the generated server integration token, which can be scoped, rate-limited, expired, and revoked.

Recommended for server integrations

x-api-key: YOUR_SERVER_INTEGRATION_TOKEN

Signed-in app sessions

Authorization: Bearer YOUR_SUPABASE_ACCESS_TOKEN

Rate Limiting: 100 requests per minute per signed-in user or integration token, plus IP-level abuse throttles.

Security Model

Every warranty request is authenticated, scoped to the owner, seller, or issuer records of the resolved user, rate-limited, and returned with no-store cache headers.

Responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Cache-Control: no-store, and Vary: Authorization, x-api-key.

Integration Tokens

Create up to 20 active tokens from a signed-in session. Warrantee shows the secret once, stores only a hash, supports read/write scopes, expiry, last-used tracking, and revocation.

Create token

POST /api/integration-tokens

Revoke token

DELETE /api/integration-tokens/:id
{ "name": "ERP production", "scopes": ["warranties:read", "warranties:write", "claims:read", "documents:read"], "rate_limit_per_minute": 100 }

Scopes: warranties:read for warranty list/detail access, warranties:write for create/update/delete, claims:read for claim records, and documents:read for document metadata without private file URLs.

Integration Notes

Use Idempotency-Key on create requests, keep a stable reference number when possible, and use scoped server-to-server integration tokens for ERP sync jobs. Never ask a client to send their Warrantee password to an integration partner.

Idempotency-Key: 8f5d07d0-erp-order-102044

CLI and scripts

Use the official Warrantee CLI in shell scripts, ERP jobs, ecommerce syncs, and CI tasks. In this repo it runs through npm scripts; after package installation or npm link it can also run as warrantee. The token belongs to the signed-in Warrantee user and never requires storing a username or password.

Recommended environment variable

export WARRANTEE_API_KEY="wrt_..."
npm run warrantee:cli -- auth status
./tools/warrantee/cli.mjs auth status
warrantee auth status
npm run warrantee:cli -- warranties list --status active --pretty
npm run warrantee:cli -- claims list --status pending --pretty
npm run warrantee:cli -- documents list --query receipt --pretty
npm run warrantee:cli -- warranties create \
  --product-name "Laptop" \
  --start-date 2026-01-01 \
  --end-date 2027-01-01 \
  --idempotency-key erp-order-102044
npm run warrantee:cli -- verify WR-12345

MCP and agent use

Run the Warrantee MCP server over stdio or call the hosted HTTP MCP endpoint at /api/mcp so agents can list, get, create, update, delete, and verify warranties; list claims; and read document metadata through the same scoped API key. In this repo use npm run warrantee:mcp; after package installation or npm link use warrantee-mcp. Agents must respect scopes, rate limits, ownership boundaries, and never ask users for passwords.

{
  "mcpServers": {
    "warrantee": {
      "command": "npm",
      "args": [
        "run",
        "warrantee:mcp",
        "--"
      ],
      "env": {
        "WARRANTEE_API_KEY": "wrt_..."
      }
    },
    "warrantee-installed": {
      "command": "warrantee-mcp",
      "env": {
        "WARRANTEE_API_KEY": "wrt_..."
      }
    }
  }
}
curl -X POST "https://warrantee.io/api/mcp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SERVER_INTEGRATION_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Agent rules

Use /llms.txt, /.well-known/agent-card.json, /.well-known/mcp.json, /.well-known/api-catalog, and /api/mcp for hosted MCP discovery. Use the public verify page for public checks. Use x-api-key only for authenticated account data.

Endpoints

GET/api/v1/warrantiesList Warranties
Parameters: page, limit, status, category
POST/api/v1/warrantiesCreate Warranty
Parameters: product_name*, start_date*, end_date*, description, serial_number, category, supplier, seller_name, seller_email
GET/api/v1/warranties/:idGet Warranty
Parameters: id (path)
PUT/api/v1/warranties/:idUpdate Warranty
Parameters: product_name, start_date, end_date, status, category, supplier
DELETE/api/v1/warranties/:idDelete Warranty
Parameters: id (path)
GET/api/v1/claimsList Claims
Parameters: page, limit, status, warranty_id
GET/api/v1/claims/:idGet Claim
Parameters: id (path)
GET/api/v1/documentsList Document Metadata
Parameters: page, limit, warranty_id, q
GET/api/v1/documents/:idGet Document Metadata
Parameters: id (path)

Example Request

curl -X GET "https://warrantee.io/api/v1/warranties?page=1&limit=10" \
  -H "x-api-key: YOUR_SERVER_INTEGRATION_TOKEN"