CloudPDF
DocsPricing
Start building

Update grant

PATCH/v1/tenants/{tenantId}/grants/{grantId}v3.3.0

Edit a grant in place — every link and embed of it follows.

Authentication#

Any one of these credentials is accepted.

API token

The deployment's static root credential (CLOUDPDF_API_AUTH_TOKENS), valid on every surface.

Tenant token

Delegated tenant JWT, valid only for its own tenant: under /v1/tenants/{tenantId}/ the path tenant must equal the token's tenant_id, and on /v1/docs/{docId} the document must belong to that tenant and the token's scope must hold the operation's document permissions, as a document token does. For servers; browsers get document tokens. Doc-scoped viewer tokens are rejected on every admin route.

Required scopegrants.manage

Parameters#

tenantIdpathstringrequired
grantIdpathstringrequired

Request body#

application/jsonGrantsUpdateRequestrequired
namestring
layerMode"shared" | "per-visitor"
layerNamestring
keepVisitorLayersboolean
visitorIdleSecondsinteger
visitorIdentityobject
fieldsobjectrequired
displayName"required" | "optional"
email"required" | "optional"
title"required" | "optional"
organization"required" | "optional"
organizationalUnit"required" | "optional"
ask"on-open" | "before-first-change"required
purposestring
privacyUrlstring<uri>
identityIdentity
scopestring[]
originsstring[]
passphrasestring
sessionTtlSecondsinteger
disabledboolean
expiresAtstring<date-time>

A complete body with every required field. Strings stand in for your own values.

{
  "name": "name",
  "layerMode": "shared",
  "layerName": "layerName",
  "keepVisitorLayers": true,
  "visitorIdleSeconds": 1,
  "visitorIdentity": {
    "fields": {
      "displayName": "required",
      "email": "required",
      "title": "required",
      "organization": "required",
      "organizationalUnit": "required"
    },
    "ask": "on-open"
  },
  "identity": null,
  "scope": [
    "scope"
  ],
  "origins": [
    "origins"
  ],
  "passphrase": "passphrase",
  "sessionTtlSeconds": 1,
  "disabled": true,
  "expiresAt": "expiresAt"
}

SDK examples#

The selected SDK is remembered across the API reference. Values are examples; replace them with identifiers and input from your application.

import { CloudPDFClient } from "@cloudpdf/sdk";

const client = new CloudPDFClient({
  token: "<token>",
});

await client.grants.update({
  tenantId: "tenantId",
  grantId: "grantId"
});

Responses#

200OK
application/jsonGrantsUpdateResponse
grantobject
idstring
tenantIdstring
docIdstring
namestring
layerMode"shared" | "per-visitor"
layerNamestring
keepVisitorLayersboolean
visitorIdleSecondsinteger
visitorIdentityobject
fieldsobject
displayName"required" | "optional"optional
email"required" | "optional"optional
title"required" | "optional"optional
organization"required" | "optional"optional
organizationalUnit"required" | "optional"optional
ask"on-open" | "before-first-change"
purposestringoptional
privacyUrlstring<uri>optional
identityIdentity
scopestring[]
originsstring[]
passphraseProtectedboolean
sessionTtlSecondsinteger
disabledboolean
archivedAtstring<date-time>
expiresAtstring<date-time>
exchangeCountinteger
lastExchangedAtstring<date-time>
createdBystring
createdAtstring<date-time>
updatedAtstring<date-time>
400Bad request
application/jsonErrorResponse
errorEngineError
code"Unknown" | "InvalidArg" | "DocNotOpen" | "DocOpenFailed" | "DocPasswordRequired" | "DocPasswordIncorrect" | "GrantPassphraseRequired" | "Aborted" | "Network" | "Unauthenticated" | "Forbidden" | "NotFound" | "WireFormat" | "RuntimeUnavailable" | "LayerVersionConflict" | "NotImplemented" | "MalformedPdf" | "SigningPending" | "SigningExpired" | "SigningVersionMismatch" | "SignatureRefused" | "ProtectedDocument" | "PayloadTooLarge" | "ObjectNumberUnavailable" | "LayerFull" | "ChangeConflict" | "UndoUnavailable" | "IdempotencyKeyReused" | "LayerDeleted" | "VisitorIdentityRequired" | "Conflict" | "EngineBusy" | "EngineRestarting" | "DocumentQuarantined" | "ThumbnailNotReady" | "TooManyRequests" | "GrantExpired" | "OriginRequired" | "OriginNotAllowed" | "FeatureNotEnabled" | "FeatureStopped" | "LicenseInvalid" | "LicenseUsageLimit" | "UpstreamError"

Why the request failed. A newer server can add codes: read one your client doesn't know as `Unknown`.

messagestring
detailsobjectoptional

What a code carries besides its message, as each code says.

403Forbidden
application/jsonErrorResponse
errorEngineError
code"Unknown" | "InvalidArg" | "DocNotOpen" | "DocOpenFailed" | "DocPasswordRequired" | "DocPasswordIncorrect" | "GrantPassphraseRequired" | "Aborted" | "Network" | "Unauthenticated" | "Forbidden" | "NotFound" | "WireFormat" | "RuntimeUnavailable" | "LayerVersionConflict" | "NotImplemented" | "MalformedPdf" | "SigningPending" | "SigningExpired" | "SigningVersionMismatch" | "SignatureRefused" | "ProtectedDocument" | "PayloadTooLarge" | "ObjectNumberUnavailable" | "LayerFull" | "ChangeConflict" | "UndoUnavailable" | "IdempotencyKeyReused" | "LayerDeleted" | "VisitorIdentityRequired" | "Conflict" | "EngineBusy" | "EngineRestarting" | "DocumentQuarantined" | "ThumbnailNotReady" | "TooManyRequests" | "GrantExpired" | "OriginRequired" | "OriginNotAllowed" | "FeatureNotEnabled" | "FeatureStopped" | "LicenseInvalid" | "LicenseUsageLimit" | "UpstreamError"

Why the request failed. A newer server can add codes: read one your client doesn't know as `Unknown`.

messagestring
detailsobjectoptional

What a code carries besides its message, as each code says.

404Not found
application/jsonErrorResponse
errorEngineError
code"Unknown" | "InvalidArg" | "DocNotOpen" | "DocOpenFailed" | "DocPasswordRequired" | "DocPasswordIncorrect" | "GrantPassphraseRequired" | "Aborted" | "Network" | "Unauthenticated" | "Forbidden" | "NotFound" | "WireFormat" | "RuntimeUnavailable" | "LayerVersionConflict" | "NotImplemented" | "MalformedPdf" | "SigningPending" | "SigningExpired" | "SigningVersionMismatch" | "SignatureRefused" | "ProtectedDocument" | "PayloadTooLarge" | "ObjectNumberUnavailable" | "LayerFull" | "ChangeConflict" | "UndoUnavailable" | "IdempotencyKeyReused" | "LayerDeleted" | "VisitorIdentityRequired" | "Conflict" | "EngineBusy" | "EngineRestarting" | "DocumentQuarantined" | "ThumbnailNotReady" | "TooManyRequests" | "GrantExpired" | "OriginRequired" | "OriginNotAllowed" | "FeatureNotEnabled" | "FeatureStopped" | "LicenseInvalid" | "LicenseUsageLimit" | "UpstreamError"

Why the request failed. A newer server can add codes: read one your client doesn't know as `Unknown`.

messagestring
detailsobjectoptional

What a code carries besides its message, as each code says.

409Conflict
application/jsonErrorResponse
errorEngineError
code"Unknown" | "InvalidArg" | "DocNotOpen" | "DocOpenFailed" | "DocPasswordRequired" | "DocPasswordIncorrect" | "GrantPassphraseRequired" | "Aborted" | "Network" | "Unauthenticated" | "Forbidden" | "NotFound" | "WireFormat" | "RuntimeUnavailable" | "LayerVersionConflict" | "NotImplemented" | "MalformedPdf" | "SigningPending" | "SigningExpired" | "SigningVersionMismatch" | "SignatureRefused" | "ProtectedDocument" | "PayloadTooLarge" | "ObjectNumberUnavailable" | "LayerFull" | "ChangeConflict" | "UndoUnavailable" | "IdempotencyKeyReused" | "LayerDeleted" | "VisitorIdentityRequired" | "Conflict" | "EngineBusy" | "EngineRestarting" | "DocumentQuarantined" | "ThumbnailNotReady" | "TooManyRequests" | "GrantExpired" | "OriginRequired" | "OriginNotAllowed" | "FeatureNotEnabled" | "FeatureStopped" | "LicenseInvalid" | "LicenseUsageLimit" | "UpstreamError"

Why the request failed. A newer server can add codes: read one your client doesn't know as `Unknown`.

messagestring
detailsobjectoptional

What a code carries besides its message, as each code says.

defaultError
application/jsonErrorResponse
errorEngineError
code"Unknown" | "InvalidArg" | "DocNotOpen" | "DocOpenFailed" | "DocPasswordRequired" | "DocPasswordIncorrect" | "GrantPassphraseRequired" | "Aborted" | "Network" | "Unauthenticated" | "Forbidden" | "NotFound" | "WireFormat" | "RuntimeUnavailable" | "LayerVersionConflict" | "NotImplemented" | "MalformedPdf" | "SigningPending" | "SigningExpired" | "SigningVersionMismatch" | "SignatureRefused" | "ProtectedDocument" | "PayloadTooLarge" | "ObjectNumberUnavailable" | "LayerFull" | "ChangeConflict" | "UndoUnavailable" | "IdempotencyKeyReused" | "LayerDeleted" | "VisitorIdentityRequired" | "Conflict" | "EngineBusy" | "EngineRestarting" | "DocumentQuarantined" | "ThumbnailNotReady" | "TooManyRequests" | "GrantExpired" | "OriginRequired" | "OriginNotAllowed" | "FeatureNotEnabled" | "FeatureStopped" | "LicenseInvalid" | "LicenseUsageLimit" | "UpstreamError"

Why the request failed. A newer server can add codes: read one your client doesn't know as `Unknown`.

messagestring
detailsobjectoptional

What a code carries besides its message, as each code says.