Skip to content
Cloudflare API
Start here
API Reference
Resource Sharing
Recipients

Create a new share recipient

client.resourceSharing.recipients.create(stringshareID, RecipientCreateParams { body_account_id, organization_id, recipient_account_id } params, RequestOptionsoptions?): RecipientCreateResponse { id, account_id, association_status, 3 more }
POST/accounts/{account_id}/shares/{share_id}/recipients

Adds a single recipient to an account-targeted resource share, granting them access to the shared resources. The recipient account must belong to the same organization as the share owner.

To replace the entire recipient list in one call, use PUT /accounts/{account_id}/shares/{share_id}/recipients instead.

Security

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
ParametersExpand Collapse
shareID: string

Share identifier tag.

maxLength32
params: RecipientCreateParams { body_account_id, organization_id, recipient_account_id }
Deprecatedbody_account_id?: string

This field has been renamed to recipient_account_id. Both names are accepted during the deprecation period.

Body param: Deprecated alias for recipient_account_id. Use recipient_account_id instead. The body field collided with the URL path parameter of the same name, which prevented SDK generators from distinguishing the source account (in the URL) from the recipient account (in the body). Both names will continue to be accepted until 2027-05-26 (see x-sunset).

maxLength32
organization_id?: string

Body param: Organization identifier.

maxLength32
recipient_account_id?: string

Body param: The account that will receive the share.

maxLength32
ReturnsExpand Collapse
RecipientCreateResponse { id, account_id, association_status, 3 more }

A recipient of a share. The association_status field tracks the lifecycle of the shared resources in the recipient account. All recipients are returned by the list endpoint regardless of status; filter client-side if only active recipients are needed.

id: string

Share Recipient identifier tag.

maxLength32
account_id: string

Account identifier.

maxLength32
association_status: "associating" | "associated" | "disassociating" | "disassociated"

The current state of the recipient relative to the share. The desired_association_status (not exposed in the response) tracks the target state set by the API; the background reconciliation workflow drives current_association_status toward it.

  • associating — The recipient was recently added; the workflow is pushing shared resources into the recipient account.
  • associated — Shared resources have been successfully applied to the recipient account.
  • disassociating — The recipient was removed (via DELETE or PUT replacement); the workflow is removing shared resources from the recipient account.
  • disassociated — Shared resources have been removed from the recipient account. The recipient record remains in the database.
One of the following:
"associating"
"associated"
"disassociating"
"disassociated"
created: string

When the share was created.

formatdate-time
modified: string

When the share was modified.

formatdate-time
resources?: Array<Resource>
error: string

Share Recipient error message.

resource_id: string

Share Resource identifier.

maxLength32
resource_version: number

Resource Version.

terminal: boolean

Whether the error is terminal or will be continually retried.

Create a new share recipient

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiEmail: process.env['CLOUDFLARE_EMAIL'], // This is the default and can be omitted
  apiKey: process.env['CLOUDFLARE_API_KEY'], // This is the default and can be omitted
});

const recipient = await client.resourceSharing.recipients.create(
  '3fd85f74b32742f1bff64a85009dda07',
  { path_account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
);

console.log(recipient.id);
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "3fd85f74b32742f1bff64a85009dda07",
    "account_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "association_status": "associating",
    "created": "2023-09-21T18:56:32.624632Z",
    "modified": "2023-09-21T18:56:32.624632Z",
    "resources": [
      {
        "error": "Recipient is missing necessary entitlement",
        "resource_id": "023e105f4ecef8ad9ca31a8372d0c353",
        "resource_version": 0,
        "terminal": true
      }
    ]
  }
}
Returns Examples
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "3fd85f74b32742f1bff64a85009dda07",
    "account_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "association_status": "associating",
    "created": "2023-09-21T18:56:32.624632Z",
    "modified": "2023-09-21T18:56:32.624632Z",
    "resources": [
      {
        "error": "Recipient is missing necessary entitlement",
        "resource_id": "023e105f4ecef8ad9ca31a8372d0c353",
        "resource_version": 0,
        "terminal": true
      }
    ]
  }
}