Skip to Content
APIResourcesAdmin APIInstallations

Installations

The Installations resource lets you register and manage MarkUp SDK installations for a workspace. An installation issues a public key the SDK uses to initialize commenting and, together with your signing key, to exchange customer-signed JWTs for MarkUp tokens.

Create installation

POST /api/v2/installations

POST /api/v2/installations
curl "https://api.markup.io/api/v2/installations" \
    -X POST \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" \
	--data '{
    "workspaceId": "1b7cd011-1526-4b6a-9cc6-030e48442d39",
    "signingKey": "-----BEGIN PUBLIC KEY-----\\nMIIBIjANBgkqhkiG9w0BAQEFA...\\n-----END PUBLIC KEY-----",
    "allowedOrigins": [
        "https://app.example.com"
    ],
    "url": "https://app.example.com",
    "name": "My App"
}'
200 OK
{
  "data": {
    "id": "6ba3bbed-4cef-49be-a06a-60faa543193e",
    "createdAt": "2026-07-17T09:32:30.264Z",
    "modifiedAt": "2026-07-17T09:32:30.264Z",
    "workspaceId": "2630cda0-26f7-4d91-af04-e8702372ca68",
    "publicKey": "some publicKey",
    "status": "active"
  }
}

Response Body - InstallationResponse

Request Body CreateInstallationRequest

OptionType
workspaceId string
signingKey string

The customer's RSA public key (PEM, RS256) used to verify SDK-signed JWTs during token exchange. Only RS256 is supported.

allowedOrigins optionalstring[]

Origins allowed to use this installation. When omitted, origin validation falls back to the SDK exchange defaults.

url optionalstring

Optional website URL. When provided, a MarkUp is created for it and attached to this installation.

name optionalstring

Optional name for the MarkUp created from url. Ignored when url is not provided.

List installations

GET /api/v2/installations

GET /api/v2/installations
curl "https://api.markup.io/api/v2/installations?workspaceId=bd8dd025-9f17-42e5-abf2-5a18aafa6722" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json"
200 OK
{
  "data": {
    "data": [
      {}
    ]
  }
}

Response Body ListInstallationResponse

OptionType
data T[]

Request Query Params WorkspaceIdRequest

OptionType
workspaceId string

Get installation

GET /api/v2/installations/:id

GET /api/v2/installations/:id
curl "https://api.markup.io/api/v2/installations/82f275ee-a4fa-47a6-bf45-35a4d82d3eac" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json"
200 OK
{
  "data": {
    "id": "b3f6f0ec-af8d-480e-b691-f2975479784a",
    "createdAt": "2026-07-17T09:32:30.265Z",
    "modifiedAt": "2026-07-17T09:32:30.265Z",
    "workspaceId": "42891298-bc85-4559-93d7-8c98dc19f129",
    "publicKey": "some publicKey",
    "status": "active"
  }
}

Response Body - InstallationResponse

Request Path Params IdRequestParam

OptionType
id string

Delete installation

DELETE /api/v2/installations/:id

DELETE /api/v2/installations/:id
curl "https://api.markup.io/api/v2/installations/5d2712e4-d4c0-4d28-9785-b45d9152f060" \
    -X DELETE \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json"
Response
204 No Content

Request Path Params IdRequestParam

OptionType
id string

InstallationResponse

OptionType
id string
createdAt Iso8601Timestamp
modifiedAt Iso8601Timestamp
deletedAt Iso8601Timestamp
workspaceId string
publicKey string

Browser-safe public identifier for this installation, used by the SDK to initialize commenting.

status string
Last updated on
WorkspaceAuthentication