Create a new share recipient

POST/accounts/{account_id}/shares/{share_id}/recipients

Adds a recipient to a resource share, granting them access to the shared resources.

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

Path ParametersExpand Collapse

account_id: string

Account identifier.

maxLength32

share_id: string

Share identifier tag.

maxLength32

Body ParametersJSONExpand Collapse

Deprecatedaccount_id: optional string

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

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: optional string

Organization identifier.

maxLength32

recipient_account_id: optional string

The account that will receive the share.

maxLength32

ReturnsExpand Collapse

errors: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

success: boolean

Whether the API call was successful.

result: optional object { id, account_id, association_status, 3 more }

id: string

Share Recipient identifier tag.

maxLength32

account_id: string

Account identifier.

maxLength32

association_status: "associating" or "associated" or "disassociating" or "disassociated"

Share Recipient association status.

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: optional array of object { error, resource_id, resource_version, terminal }

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

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/shares/$SHARE_ID/recipients \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{
          "account_id": "023e105f4ecef8ad9ca31a8372d0c353",
          "organization_id": "023e105f4ecef8ad9ca31a8372d0c353",
          "recipient_account_id": "023e105f4ecef8ad9ca31a8372d0c353"
        }'

{
  "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
      }
    ]
  }
}