CloudPDF
DocsPricing
Start building

Create grant

POST/v1/tenants/{tenantId}/grantsv3.3.0

Create a standing grant for one document — the no-backend embed credential.

The returned id is what a link page or an embed opens. Its scope gives only document permissions the caller holds itself, as tokens.issue does. Mounted only when the deployment can sign (HS256 mode) — exchange mints session JWTs, so grants exist only where minting does.

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

Request body#

application/jsonGrantsCreateRequestrequired
docIdstringrequired
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[]required
originsstring[]
passphrasestring
sessionTtlSecondsinteger
expiresAtstring<date-time>

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

{
  "docId": "docId",
  "scope": [
    "scope"
  ]
}

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.create({
  tenantId: "tenantId",
  docId: "docId",
  scope: ["scope"]
});

Responses#

200OK
application/jsonGrantsCreateResponse
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.

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.