# Provide Stream Shares from Confluent Cloud
As a data provider, you can send invites and revoke access to shared data
using the Confluent Cloud Console, the Confluent CLI, or REST APIs.
Additionally, you can describe the data you share with format and
organization information, so that its origin is clear to consumers.
To share data, you must be an administrator in your Confluent Cloud organization or
environment.
If you are using
[role-based access control (RBAC)](../security/access-control/rbac/overview.md#cloud-rbac), you must have one of
the following roles to start data sharing:
* [OrganizationAdmin](../security/access-control/rbac/predefined-rbac-roles.md#organizationadmin-role)
* [EnvironmentAdmin](../security/access-control/rbac/predefined-rbac-roles.md#environmentadmin-role)
## Enable Stream Sharing
There are some prerequisites before an organization can share data.
- If they haven’t already, an administrator must select a Stream Governance package
for the Confluent Cloud account. For more about Stream Governance, see
[Manage Stream Governance Packages in Confluent Cloud](../stream-governance/packages.md#stream-gov-packages).
- An administrator must enable the Stream Sharing feature.
- To share schema-enabled topics, your organization must use Confluent Cloud
Schema Registry. If you are using the self-managed Schema Registry, you cannot share
schema-enabled topics with Stream Sharing.
- To share data without a schema, you do not need Confluent Cloud Schema Registry.
To enable Stream Sharing:
1. Sign in to the Confluent Cloud Console.
2. From the Administration menu in the upper-right corner, select an
organization to display the **Organizations** page.
3. On the **Organizations** page, choose the organization you want to enable.
On the organization page, toggle **Stream Sharing** on.
## Stream shares
After Stream Sharing is enabled for your Confluent Cloud organization, you
can share data by inviting users through email. To share data, you must be
an administrator for the organization, environment, or cluster. You can
send one invitation to an email address. If a consumer cannot access their
email invitation, resend the invitation. You can send invitations as often
as you like until the invitation is accepted. After an invitation
is accepted, generating more invitations results in an error.
Invitations contain a token for authentication. The token is
automatically generated and added to the invitation. A token is
redeemable only once.
The consumer uses the token to get an API key and secret. The API key
and secret give the consumer read-only access to your shared topics and
schemas. Confluent restricts access to your resources with an internal
service account and RBAC. To restrict access to your data, Confluent
binds the internal service account to these internal RBAC roles:
- **StreamShareRead**: Provides read access to shared topics.
* Allows consumers to read topics and groups.
- **StreamShareSchemaRegistryRead**: Provides read access to the Schema Registry subject.
* Allows consumers to read Schema Registry subjects.
#### NOTE
You can’t directly use the internal Stream Sharing RBAC service
account or the associated RBAC roles.
The following examples show you how to share a stream with an email invitation.
### Cloud Console
To share data in Cloud Console:
1. Sign in to Confluent Cloud with an administrator account.
2. Select the environment and cluster that contains the topic you want
to share.
3. Click **Topics** in the navigation menu.
4. On the **Topics** page, take one of the following actions:
- Hover over the topic you want to share and select .
- Select a topic and then select **Actions** and point to
**Share this topic**.
The **Share** option is only available to the administrator
of a particular cluster, environment, or organization. You
cannot share topics in a resource that you don’t administer.
5. Enter the email of the person to whom you want to give read
access to the topic. Optionally, you can also specify one or
more **Schema subjects** to share with this account. Enter one
email address at a time. If the email address is incorrectly
formatted, you get an error.
#### NOTE
To view the status of all invitations to this topic, click
**Shared with**.
To resend or revoke invitations, click **Manage invites**.
6. Click **Invite** to send the invitation. A consumer has seven
days to access the data through the link provided, before the
link expires. After redemption, the data share becomes active
and remains so indefinitely until you
[revoke access](#shared-data-revoke) or the consumer
deletes (deactivates) it.
### Confluent CLI
To share topics with the Confluent CLI.
1. Sign in to Confluent Cloud with an administrator account.
```text
confluent login
```
2. Use the `invite` command to create an invite, specifying the
environment and cluster that contains the topic to share, and
the topic name. Specify the email address for the
user you want to share the data with.
```text
confluent stream-share provider invite create --email some-person@confluent.io --environment env-xyz123 --cluster lkc-10000 --topic users --schema-registry-subjects strings
```
Your response should resemble:
```text
+----------------------------+----------------------------+
| ID | ss-3vpvd |
| Consumer Name | some-person@confluent.io |
| Consumer Organization Name | |
| Cloud | Another Person |
| Status | INVITED |
| Delivery method | Email |
| ServiceAccountId | |
| SharedResourceId | |
| Invited At | 2022-09-01 15:35:17.508228 |
| | |
| Redeemed At | |
| Invite Expiration | 2022-09-08 15:35:17.508228 |
+----------------------------+----------------------------+
```
### REST API
To share data with the REST API for a schema-enabled cluster that
includes a schema subject, send an `HTTP POST` call to the
`https://api.confluent.cloud/cdx/v1/provider-shares` endpoint,
specifying the environment, cluster, any schema subjects, and
delivery method in a JSON payload.
```text
POST /cdx/v1/provider-shares
{
"delivery_method": "Email",
"consumer_restriction": {
"kind": "Email",
"email": "user@example.com"
},
"resources": [
"crn://confluent.cloud/environment=env-abc123/cloud-cluster=lkc-q55555/kafka=lkc-q55555/topic=users"
"crn://confluent.cloud/environment=env-abc123/schema-registry=lsrc-12345/subject=users-value"
]
}
```
Schema subjects are optional but require a schema-enabled cluster.
Your response should resemble:
```http
{
"api_version": "v1",
"cloud_cluster": {
"environment": "env-abc123",
"id": "lkc-q55555",
"related": "",
"resource_name": ""
},
"consumer_restriction": {
"email": "user@example.com",
"kind": "Email"
},
"consumer_user_name": "user@example.com",
"delivery_method": "Email",
"id": "ss-ex123",
"invite_expires_at": "2023-01-31T00:39:07.626255Z",
"invited_at": "2023-01-24T00:39:07.624591Z",
"kind": "ProviderShare",
"metadata": {
"created_at": "2023-01-24T00:39:07.624591Z",
"resource_name": "crn://confluent.cloud/organization=example-7abc-4abc-a123-123456789b19/environment=env-abc123/cloud-cluster=lkc-q55555/provider-share=ss-ex123",
"self": "https://api.confluent.cloud/cdx/v1/provider-shares/ss-ex123",
"updated_at": "2023-01-24T00:39:07.624591Z"
},
"provider_user": {
"id": "u-q50gkd",
"related": "",
"resource_name": ""
},
"provider_user_name": "rogert",
"service_account": {
"id": "",
"related": "",
"resource_name": ""
},
"status": {
"phase": "INVITED"
}
}
```
#### NOTE
If you share a topic from a cluster on a Confluent Cloud network, you
provide the email recipient with details on how to connect to your
private Confluent Cloud network.
## List stream shares
List the streams you have shared with other users.
### Cloud Console
1. Sign in to Confluent Cloud with an administrator account.
2. From the navigation menu, select **Data portal**.
3. View the list of shared streams in **Data shared by me**.
### Confluent CLI
To view a list of data streams you have shared:
1. Sign in to Confluent Cloud with an administrator account.
```bash
confluent login
```
2. List the shares with the `list` command.
```bash
confluent stream-share provider share list
```
Your response should resemble:
### REST API
To list shared data with an API, perform an HTTP GET against
the `https://api.confluent.cloud/cdx/v1/provider-shares` URI.
The request must also include an authorization header that
contains the API key and secret, base-64 encoded. For more
information, see
[Authentication](https://docs.confluent.io/cloud/current/api.html/#authentication).
An example request to list the shared data:
```none
GET /cdx/v1/provider-shares
```
Your response should resemble:
```none
{
"api_version": "v1",
"data": [
{
"api_version": "v1",
"cloud_cluster": {
"environment": "env-abc123",
"id": "lkc-q55555",
"related": "",
"resource_name": ""
},
"consumer_restriction": {
"email": "user@example.com",
"kind": "Email"
},
"consumer_user_name": "user@example.com",
"delivery_method": "Email",
"id": "ss-ex123",
"invite_expires_at": "2023-01-31T00:39:07.626255Z",
"invited_at": "2023-01-24T00:39:07.624591Z",
"kind": "ProviderShare",
"metadata": {
"created_at": "2023-01-24T00:39:07.624591Z",
"resource_name": "crn://confluent.cloud/organization=example-7abc-4abc-a123-123456789b19/environment=env-abc123/cloud-cluster=lkc-q55555/provider-share=ss-ex123",
"self": "https://api.confluent.cloud/cdx/v1/provider-shares/ss-ex123",
"updated_at": "2023-01-24T00:39:07.624591Z"
},
"provider_user": {
"id": "u-q50gkd",
"related": "",
"resource_name": ""
},
"provider_user_name": "rogert",
"service_account": {
"id": "",
"related": "",
"resource_name": ""
},
"status": {
"phase": "INVITED"
}
},
{
"api_version": "v1",
"cloud_cluster": {
"environment": "env-abc123",
"id": "lkc-q55555",
"related": "",
"resource_name": ""
},
"consumer_restriction": {
"email": "user@example.com",
"kind": "Email"
},
"consumer_user_name": "user@example.com",
"delivery_method": "Email",
"id": "ss-exabc",
"invite_expires_at": "2023-01-31T00:31:13.108718Z",
"invited_at": "2023-01-24T00:31:13.106964Z",
"kind": "ProviderShare",
"metadata": {
"created_at": "2023-01-24T00:31:13.106964Z",
"resource_name": "crn://confluent.cloud/organization=example-7abc-4abc-a123-123456789b19/environment=env-abc123/cloud-cluster=lkc-q55555/provider-share=ss-exabc",
"self": "https://api.confluent.cloud/cdx/v1/provider-shares/ss-exabc",
"updated_at": "2023-01-24T00:31:13.106964Z"
},
"provider_user": {
"id": "u-q50gkd",
"related": "",
"resource_name": ""
},
"provider_user_name": "rogert",
"service_account": {
"id": "",
"related": "",
"resource_name": ""
},
"status": {
"phase": "INVITED"
}
},
],
"kind": "ProviderShareList",
"metadata": {}
}
```
## Revoke stream share access
You can revoke access to shared data with the Confluent Cloud Console by
revoking access, and by deleting a share with the Confluent CLI or
REST APIs.
### Cloud Console
1. Sign in to Confluent Cloud with an administrator account.
2. From the navigation menu, select **Data portal**.
3. In **Data shared by me**, select the data that you want to
revoke access to.
4. Select the **Shared with** tab.
5. Select the account you want to revoke and click **Revoke access**.
### Confluent CLI
To revoke access to shared data with the Confluent CLI.
1. Sign in to Confluent Cloud with an administrator account.
```bash
confluent login
```
2. If you don’t know the identifier for the share to delete,
list the shares with the `list` command.
```bash
confluent stream-share provider share list
```
3. Choose the share to delete and use the `delete` command,
specifying the share identifier.
```bash
confluent stream-share delete ss-exabc
```
Your response should resemble:
```bash
Deleted provider share "ss-exabc".
```
### REST API
1. Optionally list the shares as described in
[List stream shares](#list-shared-streams) to get the identifier for the
share you want to delete.
2. Send an `HTTP DELETE` message to
`https://api.confluent.cloud/cdx/v1/provider-shares` URI,
specifying the ID for the share to be deleted. This example
deletes share `ss-exabc`.
The request must also include an authorization header that
contains the API key and secret, base-64 encoded. For more
information, see
[Authentication](https://docs.confluent.io/cloud/current/api.html/#authentication).
```none
DELETE /cdx/v1/provider-shares/ss-exabc
```
If the call succeeds, you receive a `204 No Content` in response.
## Describe stream shares
You can annotate your shared data with a description, organization
name and logo, schema for the data, and more using the
Cloud Console or the REST API.
To annotate or modify shared data:
### Cloud Console
1. Sign in to Confluent Cloud with an administrator account.
2. From the navigation menu, select **Data portal**.
3. In **Data shared by me**, select the data that you want to
annotate or modify.
4. From the shared topic details page, select **Edit share content**.
5. Modify or add the following optional descriptive details:
- Display name
- Schema subjects
- Organization description
- Contact email
- Logo
#### NOTE
Shared data includes a topic description and any tags
added to the topic. You can add or edit tags and the
topic description from the topic details page.
6. Click **Save** to save your changes.
### REST API
You can update or add information to a shared resource by
making a PATCH call to the
`https://api.confluent.cloud/cdx/v1/provider-shared-resources/`
URL, specifying the share you want to modify.
```text
PATCH cdx/v1/provider-shared-resources/sr-12abc
{
"resources": [
"crn://confluent.cloud/environment=env-abc123/cloud-cluster=lkc-q55555/kafka=lkc-q55555/topic=user"
],
"display_name": "Stock Trades",
"organization_description": "ABC Corp is the biggest online retailer",
"organization_contact": "jane.doe@example.com"
}
```
The response resembles:
```text
{
"api_version": "v1",
"cloud_cluster": {
"environment": "env-abc123",
"id": "lkc-q55555",
"related": "",
"resource_name": ""
},
"cluster_name": "cluster_1",
"crn": "crn://confluent.cloud/organization=example-7abc-4abc-a123-123456789b19/environment=env-abc123/cloud-cluster=lkc-q55555/kafka=lkc-q55555/topic=user",
"display_name": "Stock Trades",
"environment_name": "test",
"id": "sr-12abc",
"kind": "ProviderSharedResource",
"logo_url": "",
"metadata": {
"created_at": "2023-01-24T00:31:12.930903Z",
"resource_name": "crn://confluent.cloud/organization=example-7abc-4abc-a123-123456789b19/environment=env-abc123/cloud-cluster=lkc-q55555/provider-shared-resource=sr-12abc",
"self": "https://api.confluent.cloud/cdx/v1/provider-shared-resources/sr-12abc",
"updated_at": "2023-01-24T00:31:13.103715Z"
},
"organization_contact": "jane.doe@example.com",
"organization_description": "ABC Corp is the biggest online retailer",
"organization_name": "Confluent",
"resources": [
"crn://confluent.cloud/organization=example-7abc-4abc-a123-123456789b19/environment=env-abc123/cloud-cluster=lkc-q55555/kafka=lkc-q55555/topic=user"
],
"schemas": [],
"tags": null
}
```