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": "6f696025-44b1-4144-bd2b-21f7f15e3dd0",
    "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": "f9ddb107-1a75-4d8a-9728-e70555622047",
    "createdAt": "2026-07-23T17:45:55.647Z",
    "modifiedAt": "2026-07-23T17:45:55.648Z",
    "workspaceId": "bff9120d-a5d7-41ec-87a0-3054df0ca5cb",
    "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=5da3fd57-0756-4b7d-9971-8aa69280c0be" \
    -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/c8bd7438-39f3-40af-ae50-816eee83520e" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json"
200 OK
{
  "data": {
    "id": "04544712-5205-4cf2-8921-26a8c402a83f",
    "createdAt": "2026-07-23T17:45:55.648Z",
    "modifiedAt": "2026-07-23T17:45:55.648Z",
    "workspaceId": "c851064e-8d04-4588-b3f6-18cf3626434c",
    "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/504a5cb2-8e81-4a8b-92ec-a627570825be" \
    -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