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": "baa61938-0d9a-4092-841a-12750690b91c",
    "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": "cbc795cf-2d20-4c74-9ac2-9e3ba0213199",
    "createdAt": "2026-10-23T12:00:10.822Z",
    "modifiedAt": "2026-10-23T12:00:10.822Z",
    "workspaceId": "fd8b4a7a-808f-45ea-82cb-85c436afdc32",
    "publicKey": "some publicKey",
    "status": "active",
    "allowedOrigins": [
      "https://app.example.com"
    ],
    "markupId": null
  }
}

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=21fa1621-6656-4b7f-a022-2ce23ecf512d" \
    -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/783f966b-8ece-4a6c-89cc-af325ab1e4f7" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json"
200 OK
{
  "data": {
    "id": "95956886-dc7a-447a-bbee-a722cbffe13f",
    "createdAt": "2026-10-23T12:00:10.822Z",
    "modifiedAt": "2026-10-23T12:00:10.822Z",
    "workspaceId": "282344cc-d0f2-4e35-8481-77d092433f94",
    "publicKey": "some publicKey",
    "status": "active",
    "allowedOrigins": [
      "https://app.example.com"
    ],
    "markupId": null
  }
}

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/cb7d2f8c-e79d-4903-bf48-4f288246ea1f" \
    -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
allowedOrigins string[] | null
markupId string | null

The MarkUp (project) id this installation is attached to, if any.

WorkspaceAuthentication