> ## Documentation Index
> Fetch the complete documentation index at: https://synthetiq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sharing

> Share entities with users and manage publisher access

Entities can be shared directly with other users or published to an organization store. Sharing grants access to install and use the entity. Publisher access grants the ability to push new versions.

## Share entity

```bash theme={null}
POST /api/entities/{entityId}/shares
```

| Parameter | Type | Required | Description                            |
| --------- | ---- | -------- | -------------------------------------- |
| `emails`  | body | Yes      | Array of email addresses to share with |

Returns results showing which shares were created, which users already had access, and which emails were not found on the platform.

**Authentication:** Entity access + `entities:share` scope. Sharing with users outside your organization additionally requires `entities:share_external` scope.

## List shares for entity

```bash theme={null}
GET /api/entities/{entityId}/shares
```

Returns the list of users this entity is shared with. Results are filtered based on the requesting user's permissions.

**Authentication:** Entity access required.

## Remove share

```bash theme={null}
DELETE /api/entities/{entityId}/shares/{shareId}
```

Revokes a user's access to the entity.

**Authentication:** Must be the user who created the share.

## List entities shared with me

```bash theme={null}
GET /api/entities/shared-with-me
```

| Parameter | Type  | Description                                               |
| --------- | ----- | --------------------------------------------------------- |
| `type`    | query | Filter by entity type: `app`, `service`, `chat_extension` |

Returns all entities other users have shared with the authenticated user.

**Authentication:** User authentication required.

## List entities I've shared

```bash theme={null}
GET /api/entities/shares
```

| Parameter | Type  | Description           |
| --------- | ----- | --------------------- |
| `type`    | query | Filter by entity type |

Returns all shares the authenticated user has created.

**Authentication:** User authentication required.

## Publishers

Publishers can push new versions of an entity. When an entity is created, the creating user is automatically the first publisher.

### List publishers

```bash theme={null}
GET /api/entities/{entityId}/publishers
```

Returns all users with publish access to the entity.

**Authentication:** Entity access required.

### Add publisher

```bash theme={null}
POST /api/entities/{entityId}/publishers
```

| Parameter | Type | Required | Description                     |
| --------- | ---- | -------- | ------------------------------- |
| `userId`  | body | Yes      | User ID to grant publish access |

**Authentication:** Entity access + publisher role required.

### Check publisher status

```bash theme={null}
GET /api/entities/{entityId}/publishers/me
```

Returns whether the authenticated user has publisher access to this entity.

**Authentication:** User authentication required.

### Remove publisher

```bash theme={null}
DELETE /api/entities/{entityId}/publishers/{userId}
```

Cannot remove the last publisher from an entity — at least one publisher must always exist.

**Authentication:** Entity access + publisher role required.

## Access hierarchy

When a user requests access to an entity, the platform checks the following in order:

1. **Publisher** — user is a publisher of the entity
2. **Direct share** — entity was shared directly with the user
3. **Organization store** — entity is published to a store the user's organization can access
4. **Public store** — entity is in a publicly visible store

If any of these checks pass, access is granted.