---
title: "Update grant"
description: "Edit a grant in place — every link and embed of it follows."
source: "https://www.cloudpdf.com/docs/api-reference/grants/update"
---

# 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.

- **apiToken** — The deployment's static root credential (CLOUDPDF\_API\_AUTH\_TOKENS), valid on every surface.
- **tenantToken** — 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 scope:** `grants.manage`

## Parameters

- `tenantId` string (path) — required
- `grantId` string (path) — required

## Request body

`application/json` — GrantsUpdateRequest

- `name` string
- `layerMode` "shared" | "per-visitor"
- `layerName` string
- `keepVisitorLayers` boolean
- `visitorIdleSeconds` integer
- `visitorIdentity` object
  - `fields` object — required
    - `displayName` "required" | "optional"
    - `email` "required" | "optional"
    - `title` "required" | "optional"
    - `organization` "required" | "optional"
    - `organizationalUnit` "required" | "optional"
  - `ask` "on-open" | "before-first-change" — required
  - `purpose` string
  - `privacyUrl` string\<uri>
- `identity` Identity
- `scope` string\[]
- `origins` string\[]
- `passphrase` string
- `sessionTtlSeconds` integer
- `disabled` boolean
- `expiresAt` string\<date-time>

**Example**

```json
{
  "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

**TypeScript**

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

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

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

**Python**

```python
from cloudpdf import CloudPDFClient

client = CloudPDFClient(
    token="<token>",
)

client.grants.update(
    tenant_id="tenantId",
    grant_id="grantId",
)
```

**PHP**

```php
use CloudPDF\CloudPDFClient;

$client = new CloudPDFClient(
    token: '<token>',
);

$client->grants->update(
    'tenantId',
    'grantId',
    new GrantsUpdateRequest([]),
);
```

**.NET**

```csharp
using CloudPDF;

var client = new CloudPDFClient(
    "<token>"
);

await client.Grants.UpdateAsync(
    new GrantsUpdateRequest { TenantId = "tenantId", GrantId = "grantId" }
);
```

**Go**

```go
import (
    "context"

    cloudpdf "github.com/embedpdf/cloudpdf-sdk-go/v3"
    client "github.com/embedpdf/cloudpdf-sdk-go/v3/client"
    option "github.com/embedpdf/cloudpdf-sdk-go/v3/option"
)

client := client.NewClient(
    option.WithToken("<token>"),
)

request := &cloudpdf.GrantsUpdateRequest{
    TenantID: "tenantId",
    GrantID: "grantId",
}
client.Grants.Update(
    context.TODO(),
    request,
)
```

**Java**

```java
import com.cloudpdf.api.CloudPDFClient;

CloudPDFClient client = CloudPDFClient
    .builder()
    .token("<token>")
    .build();

client.grants().update(
    "tenantId",
    "grantId",
    GrantsUpdateRequest
        .builder()
        .build()
);
```

**Ruby**

```ruby
require "cloudpdf"

client = CloudPDF::Client.new(
  token: "<token>"
)

client.grants.update(
  tenant_id: "tenantId",
  grant_id: "grantId"
)
```

## Responses

### 200 — OK

`application/json` — GrantsUpdateResponse

- `grant` object — required
  - `id` string — required
  - `tenantId` string — required
  - `docId` string — required
  - `name` string — required
  - `layerMode` "shared" | "per-visitor" — required
  - `layerName` string — required
  - `keepVisitorLayers` boolean — required
  - `visitorIdleSeconds` integer — required
  - `visitorIdentity` object — required
    - `fields` object — required
      - `displayName` "required" | "optional"
      - `email` "required" | "optional"
      - `title` "required" | "optional"
      - `organization` "required" | "optional"
      - `organizationalUnit` "required" | "optional"
    - `ask` "on-open" | "before-first-change" — required
    - `purpose` string
    - `privacyUrl` string\<uri>
  - `identity` Identity — required
  - `scope` string\[] — required
  - `origins` string\[] — required
  - `passphraseProtected` boolean — required
  - `sessionTtlSeconds` integer — required
  - `disabled` boolean — required
  - `archivedAt` string\<date-time> — required
  - `expiresAt` string\<date-time> — required
  - `exchangeCount` integer — required
  - `lastExchangedAt` string\<date-time> — required
  - `createdBy` string — required
  - `createdAt` string\<date-time> — required
  - `updatedAt` string\<date-time> — required

### 400 — Bad request

`application/json` — ErrorResponse

- `error` EngineError — required
  - `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" — required — Why the request failed. A newer server can add codes: read one your client doesn't know as \`Unknown\`.
  - `message` string — required
  - `details` object — What a code carries besides its message, as each code says.

### 403 — Forbidden

`application/json` — ErrorResponse

- `error` EngineError — required
  - `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" — required — Why the request failed. A newer server can add codes: read one your client doesn't know as \`Unknown\`.
  - `message` string — required
  - `details` object — What a code carries besides its message, as each code says.

### 404 — Not found

`application/json` — ErrorResponse

- `error` EngineError — required
  - `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" — required — Why the request failed. A newer server can add codes: read one your client doesn't know as \`Unknown\`.
  - `message` string — required
  - `details` object — What a code carries besides its message, as each code says.

### 409 — Conflict

`application/json` — ErrorResponse

- `error` EngineError — required
  - `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" — required — Why the request failed. A newer server can add codes: read one your client doesn't know as \`Unknown\`.
  - `message` string — required
  - `details` object — What a code carries besides its message, as each code says.

### default — Error

`application/json` — ErrorResponse

- `error` EngineError — required
  - `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" — required — Why the request failed. A newer server can add codes: read one your client doesn't know as \`Unknown\`.
  - `message` string — required
  - `details` object — What a code carries besides its message, as each code says.
