CloudPDF
DocsPricing
Start building

List grants

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

List grants in the tenant, newest first, cursor-paginated.

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
limitqueryintegerdefault 100
cursorquerystring
docIdquerystring
archivedqueryboolean

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.list({
  tenantId: "tenantId"
});

Responses#

200OK
application/jsonGrantsListResponse
grantsobject[]
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>
nextCursorstring
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.

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.