Skip to content
Cloudflare API
Start here
API Reference
Resource Sharing

Trigger a share creation

POST/accounts/{account_id}/shares

Creates a share that makes a resource available to specific accounts in the caller’s organization, or to the whole organization.

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
minLength32
Body ParametersJSONExpand Collapse
name: string

The name of the share.

excluded_recipients: optional array of object { account_id }

Accounts to exclude from an organization-targeted share. Only allowed when recipients contains no account entries. The share owner cannot be excluded. Duplicate entries are ignored.

account_id: string

The account to exclude from the organization-targeted share.

maxLength32
minLength32
recipients: optional 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
minLength32
organization_id: optional string

Organization identifier.

maxLength32
minLength32
recipient_account_id: optional string

The account that will receive the share.

maxLength32
minLength32
resources: optional array of object { meta, resource_account_id, resource_id, resource_type }
meta: unknown

Resource Metadata.

resource_account_id: string

The account that owns the resource. Must match the account_id in the path.

maxLength32
minLength32
resource_id: string

Identifier assigned by the service that owns the shared resource.

resource_type: "custom-ruleset" or "gateway-policy" or "gateway-destination-ip" or 4 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"
"trust-grant"
tags: optional map[string]

Tags associated with the share.

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, 13 more }
id: string

Share identifier tag.

maxLength32
minLength32
account_id: string

Account identifier.

maxLength32
minLength32
account_name: string

The display name of an account.

created: string

When the object was created.

formatdate-time
modified: string

When the object was last modified.

formatdate-time
name: string

The name of the share.

organization_id: string

Organization identifier.

maxLength32
minLength32
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
minLength32
created: string

When the object was created.

formatdate-time
meta: unknown

Resource Metadata.

modified: string

When the object was last modified.

formatdate-time
resource_account_id: string

Account identifier.

maxLength32
minLength32
resource_id: string

Identifier assigned by the service that owns the shared resource.

resource_type: "custom-ruleset" or "gateway-policy" or "gateway-destination-ip" or 4 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"
"trust-grant"
resource_version: number

Resource Version.

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

Resource Status.

One of the following:
"active"
"deleting"
"deleted"
tags: optional map[string]

Tags associated with the share. Included in create and update responses when tags are supplied, and in read responses when the include_tags_from parameter is set.

Trigger a share creation

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"
        }'
{
  "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": "0a679032-bbb2-4b7e-9acc-dd5c5cb27a17",
        "resource_type": "custom-ruleset",
        "resource_version": 0,
        "status": "active"
      }
    ],
    "tags": {
      "foo": "string"
    }
  }
}
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": "0a679032-bbb2-4b7e-9acc-dd5c5cb27a17",
        "resource_type": "custom-ruleset",
        "resource_version": 0,
        "status": "active"
      }
    ],
    "tags": {
      "foo": "string"
    }
  }
}