integrations

Create a long-lived API token

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}
Close
POST /auth/generate-token
Access token

With scopes, mints a scoped automation token (lifetime from ttlDays or the configured default, 365 days when unset, never more than 400) and returns the token once with its id, label, scopes and expiry; returns 403 while automation tokens are turned off and 400 for an empty or unsupported scope list. Without scopes, mints a legacy full-access token valid for 5 years and returns only token and validTill (no id); sending label or ttlDays without scopes returns 400. An inactive user gets 401.

application/json

Body Required

  • scopes array[string]

    Automation scopes to grant. Presence of this field mints a scoped automation token; must be non-empty and a subset of the allowed scopes.

    Values are cases:create, codes:create, or exports:create.

  • label string

    Human-readable label for the automation token (e.g. "Zapier – intake").

  • ttlDays number

    Token lifetime in days (automation tokens only, 1–400). Defaults to the configured automation TTL (~365).

    Minimum value is 1, maximum value is 400.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data attributes object
      • createdAt string(date-time) Required
      • updatedAt string(date-time) Required
      • id string Required
      • token string Required

        The token value. Returned once at mint time only.

      • validTill string(date-time) Required
      • scopes array[string]

        Values are cases:create, codes:create, or exports:create.

      • label string
    • statusCode number Required
    • timestamp string(date-time) Required
POST /auth/generate-token 
curl \
 --request POST 'http://api.example.com/auth/generate-token' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{
  "scopes": [
    "cases:create"
  ],
  "label": "string",
  "ttlDays": 42.0
}'
Request examples 
{
  "scopes": [
    "cases:create"
  ],
  "label": "string",
  "ttlDays": 42.0
}
Response examples (200) 
{
  "data": {
    "createdAt": "2026-01-15T14:30:00.000Z",
    "updatedAt": "2026-01-15T14:30:00.000Z",
    "id": "507f1f77bcf86cd799439011",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI2NWExYjJjMyJ9.c2lnbmF0dXJl",
    "validTill": "2027-01-15T10:15:00.000Z",
    "scopes": [
      "cases:create"
    ],
    "label": "Intake sync"
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}