Create a new share

POST/accounts/{account_id}/shares

Creates a new resource share for sharing Cloudflare resources with other accounts or organizations.

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

Body ParametersJSONExpand Collapse

name: string

The name of the share.

recipients: array of object { account_id, organization_id, recipient_account_id }

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

resources: array of object { meta, resource_account_id, resource_id, resource_type }

meta: unknown

Resource Metadata.

resource_account_id: string

Account identifier.

maxLength32

resource_id: string

Share Resource identifier.

maxLength32

resource_type: "custom-ruleset" or "gateway-policy" or "gateway-destination-ip" or 3 more

Resource Type.

One of the following:

"custom-ruleset"

"gateway-policy"

"gateway-destination-ip"

"gateway-block-page-settings"

"gateway-extended-email-matching"

"idp-federation-grant"

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, account_name, 12 more }

id: string

Share identifier tag.

maxLength32

account_id: string

Account identifier.

maxLength32

account_name: string

The display name of an account.

created: string

When the share was created.

formatdate-time

modified: string

When the share was modified.

formatdate-time

name: string

The name of the share.

organization_id: string

Organization identifier.

maxLength32

status: "active" or "deleting" or "deleted"

One of the following:

"active"

"deleting"

"deleted"

target_type: "account" or "organization"

One of the following:

"account"

"organization"

associated_recipient_count: optional number

The number of recipients in the ‘associated’ state. This field is only included when requested via the ‘include_recipient_counts’ parameter.

associating_recipient_count: optional number

The number of recipients in the ‘associating’ state. This field is only included when requested via the ‘include_recipient_counts’ parameter.

disassociated_recipient_count: optional number

The number of recipients in the ‘disassociated’ state. This field is only included when requested via the ‘include_recipient_counts’ parameter.

disassociating_recipient_count: optional number

The number of recipients in the ‘disassociating’ state. This field is only included when requested via the ‘include_recipient_counts’ parameter.

kind: optional "sent" or "received"

One of the following:

"sent"

"received"

resources: optional array of object { id, created, meta, 6 more }

A list of resources that are part of the share. This field is only included when requested via the ‘include_resources’ parameter.

id: string

Share Resource identifier.

maxLength32

created: string

When the share was created.

formatdate-time

meta: unknown

Resource Metadata.

modified: string

When the share was modified.

formatdate-time

resource_account_id: string

Account identifier.

maxLength32

resource_id: string

Share Resource identifier.

maxLength32

resource_type: "custom-ruleset" or "gateway-policy" or "gateway-destination-ip" or 3 more

Resource Type.

One of the following:

"custom-ruleset"

"gateway-policy"

"gateway-destination-ip"

"gateway-block-page-settings"

"gateway-extended-email-matching"

"idp-federation-grant"

resource_version: number

Resource Version.

status: "active" or "deleting" or "deleted"

Resource Status.

One of the following:

"active"

"deleting"

"deleted"

Create a new share

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/shares \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{
          "name": "My Shared WAF Managed Rule",
          "recipients": [
            {}
          ],
          "resources": [
            {
              "meta": {},
              "resource_account_id": "023e105f4ecef8ad9ca31a8372d0c353",
              "resource_id": "023e105f4ecef8ad9ca31a8372d0c353",
              "resource_type": "custom-ruleset"
            }
          ]
        }'

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "3fd85f74b32742f1bff64a85009dda07",
    "account_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "account_name": "Account A",
    "created": "2023-09-21T18:56:32.624632Z",
    "modified": "2023-09-21T18:56:32.624632Z",
    "name": "My Shared WAF Managed Rule",
    "organization_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "status": "active",
    "target_type": "account",
    "associated_recipient_count": 10,
    "associating_recipient_count": 1,
    "disassociated_recipient_count": 0,
    "disassociating_recipient_count": 0,
    "kind": "sent",
    "resources": [
      {
        "id": "023e105f4ecef8ad9ca31a8372d0c353",
        "created": "2023-09-21T18:56:32.624632Z",
        "meta": {},
        "modified": "2023-09-21T18:56:32.624632Z",
        "resource_account_id": "023e105f4ecef8ad9ca31a8372d0c353",
        "resource_id": "023e105f4ecef8ad9ca31a8372d0c353",
        "resource_type": "custom-ruleset",
        "resource_version": 0,
        "status": "active"
      }
    ]
  }
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "id": "3fd85f74b32742f1bff64a85009dda07",
    "account_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "account_name": "Account A",
    "created": "2023-09-21T18:56:32.624632Z",
    "modified": "2023-09-21T18:56:32.624632Z",
    "name": "My Shared WAF Managed Rule",
    "organization_id": "023e105f4ecef8ad9ca31a8372d0c353",
    "status": "active",
    "target_type": "account",
    "associated_recipient_count": 10,
    "associating_recipient_count": 1,
    "disassociated_recipient_count": 0,
    "disassociating_recipient_count": 0,
    "kind": "sent",
    "resources": [
      {
        "id": "023e105f4ecef8ad9ca31a8372d0c353",
        "created": "2023-09-21T18:56:32.624632Z",
        "meta": {},
        "modified": "2023-09-21T18:56:32.624632Z",
        "resource_account_id": "023e105f4ecef8ad9ca31a8372d0c353",
        "resource_id": "023e105f4ecef8ad9ca31a8372d0c353",
        "resource_type": "custom-ruleset",
        "resource_version": 0,
        "status": "active"
      }
    ]
  }
}