Albums created by your app can be shared between users, with options to allow
those users to comment on, or contribute their own media items to the album.

To share an album through the Google Photos Library API, your app needs to do the following:

1. [Create an album](https://developers.google.com/photos/library/legacy/guides/manage-albums.md.txt#creating-new-album) on behalf of a user.
2. [Set that album to shared](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#sharing-album).

> [!NOTE]
> **Note:** Before sharing an album, obtain explicit consent from the user, and make sure to follow the [UX guidelines](https://developers.google.com/photos/library/legacy/guides/ux-guidelines.md.txt#in-app-sharing).

## Required authentication scope

In order to share content, your app must request the `photoslibrary.sharing`
[authorization scope](https://developers.google.com/photos/library/legacy/guides/authorization.md.txt).

## Sharing an album

Before sharing an album, take the following considerations into account:

- Your app can only share albums it has created. Albums created by other apps, including Google Photos, can't be shared by your app.
- When your app shares an album via the Library API, a [shareable URL](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#Album.ShareInfo) is generated that anyone can use to access the album.
- For albums shared via the API, the album's owner can [turn off link sharing](https://support.google.com/photos/answer/9789702#controlsharedalbums) or unshare the album in the Google Photos app, potentially preventing your app from joining new users to it.

To share an album:

1. Follow the [UX guidelines](https://developers.google.com/photos/library/legacy/guides/ux-guidelines.md.txt#in-app-sharing) and obtain explicit consent from the user to create a shared album.
2. [Create the album](https://developers.google.com/photos/library/legacy/guides/manage-albums.md.txt#creating-new-album), and record its `albumId`. If you've already created the album, you can retrieve its `albumId` by [listing the user's albums](https://developers.google.com/photos/library/legacy/guides/list.md.txt#listing-albums).
3. Call [`albums.share`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums/share.md.txt) using the relevant `albumId`, along with the [share options](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#share-options) you want to set.
4. Record the [`shareToken`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#Album.ShareInfo) value in the response. The share token is an identifier for a shared album that can be used across different user accounts.
5. Another user can now authenticate with your app, then [join](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#joining-shared-album), [leave](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#leaving-shared-album), or [retrieve the details](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#retrieving-shared-albums-share-tokens) of the shared album using its `shareToken`.

### Share options

The following options can be set when sharing an album using the
[`sharedAlbumOptions`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#Album.SharedAlbumOptions)
parameter. If the options aren't explicitly set, the default values are used.

| Property | Default value | Description |
|---|---|---|
| `isCollaborative` | `false` | Sets whether other Google Photos users can add content to the shared album. |
| `isCommentable` | `false` | Sets whether other Google Photos users can comment on the shared album. |

### Example request

The following request shares an album by calling `albums.share` with options. A
[`shareInfo`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#Album.ShareInfo) property
is returned in the response that describes the album's
[sharing properties](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#shared-album-properties).

### REST

Here is a POST request header to share an album:

```
POST https://photoslibrary.googleapis.com/v1/albums/album-id:share
Content-type: application/json
Authorization: Bearer oauth2-token
```

In the request body, specify the share options.

```restructuredtext
{
  "sharedAlbumOptions": {
    "isCollaborative": "true",
    "isCommentable": "true"
  }
}
```

This request returns the following response:

```restructuredtext
{
  "shareInfo": {
    "sharedAlbumOptions": {
      "isCollaborative": "true",
      "isCommentable": "true"
    },
    "shareableUrl": "shareable-url",
    "shareToken": "share-token",
    "isJoinable": "true-if-users-can-join-album",
    "isJoined": "true-if-user-is-joined-to-album",
    "isOwned": "true-if-user-owns-album"
  }
}
```

### Java

```java
try {

  SharedAlbumOptions options =
          // Set the options for the album you want to share
          SharedAlbumOptions.newBuilder()
          .setIsCollaborative(true)
          .setIsCommentable(true)
          .build();
  ShareAlbumResponse response = photosLibraryClient.shareAlbum(albumId, options);

  // The response contains the shareInfo object, a url, and a token for sharing
  ShareInfo info = response.getShareInfo();
  // Link to the shared album
  String url = info.getShareableUrl();
  String shareToken = info
  // The share token which other users of your app can use to join the album you shared
      .getShareToken();
  SharedAlbumOptions sharedOptions = info
      // The options set when sharing this album
      .getSharedAlbumOptions();

} catch (ApiException e) {
  // Handle error
}
```

### PHP

```php
// Set the options for the album you want to share
$options = new SharedAlbumOptions();
$options->setIsCollaborative(true);
$options->setIsCommentable(true);
try {
    $response = $photosLibraryClient->shareAlbum($albumId, ['sharedAlbumOptions' => $options]);
    // The response contains the shareInfo object, a url, and a token for sharing
    $shareInfo = $response->getShareInfo();
    // Link to the shared album
    $url = $shareInfo->getShareableUrl();
    // The share token which other users of your app can use to join the album you shared
    $shareToken = $shareInfo->getShareToken();
    // The options set when sharing this album
    $sharedOptions = $shareInfo->getSharedAlbumOptions();
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}
```

### Shared album properties

For albums that have been created and shared by your app, all responses that
return an [`album`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#resource-album)
include an additional property,
[`shareInfo`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#Album.ShareInfo). This
property is returned when [sharing](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#sharing-album),
[listing](https://developers.google.com/photos/library/legacy/guides/list.md.txt#listing-albums) or
[retrieving](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums/get.md.txt) albums.

The following table lists the
[`shareInfo`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#Album.ShareInfo)
properties:

| Properties ||
|---|---|
| `sharedAlbumOptions` | Options that describe whether someone can [add media items to or comment on a shared album](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#share-options). |
| `shareableUrl` | A link to the shared Google Photos album. Anyone with the link can view the contents of the album, so it should be treated with care. The `shareableUrl` field is only returned if the album has [link sharing turned on](https://support.google.com/photos/answer/9789702#controlsharedalbums). If a user is already joined to an album that isn't link-shared, they can use the album's `productUrl` to access it instead. A `shareableUrl` is invalidated if the owner turns off link sharing in the Google Photos app, or if the album is unshared. |
| `shareToken` | A token that is used to [join](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#joining-shared-album), [leave](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#leaving-shared-album), or [retrieve the details](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#retrieving-shared-albums-share-tokens) of a shared album on behalf of a user who isn't the owner. A `shareToken` is invalidated if the owner turns off link sharing in the Google Photos app, or if the album is unshared. |
| `isJoinable` | `True` if the album can be joined by users. |
| `isJoined` | `True` if the user is joined to the album. This is always true for the owner of the album. |
| `isOwned` | `True` if the user owns the album. |

> [!CAUTION]
> **Caution:** Anyone with an album's `shareableUrl` can view the album's contents.

## Unsharing an album

To unshare an album your app has previously shared, call
[`albums.unshare`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums/unshare.md.txt) using the
album's `albumId`.

In addition to the album no longer being shared, the following things will
happen:

- All non-owners will lose access to the album. This includes people who have had the album [specifically shared](https://support.google.com/photos/answer/9789702#controlsharedalbums) with them through the Google Photos app.
- All content added by non-owners will be removed from the album.
- If a user has previously added the contents of the album to their library, the contents will be retained in their library.
- The album's share token and shareable URL will be invalidated.

### Example request

### REST

Here is a POST request header to unshare an album:

```
POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare
Content-type: application/json
Authorization: Bearer oauth2-token
```

The request body must be empty.

If the request was successful, it returns an empty response with an HTTP
success status code. If the request was not successful, it returns an HTTP
error status code with an error message.

### Java

```java
try {
  // If this call is not successful, an exception is raised
  photosLibraryClient.unshareAlbum(albumId);
} catch (ApiException e) {
  // Handle error
}
```

### PHP

```php
try {
    // Mark the album as private and no longer shared
    // If this call is not successful, an exception is raised
    $photosLibraryClient->unshareAlbum($albumId);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}
```

## Retrieving shared albums and share tokens

A [shared album's details](https://developers.google.com/photos/library/legacy/reference/rest/v1/sharedAlbums.md.txt),
including its share token, are returned when your app shares an album. You can
also retrieve those details afterwards in the following ways.

If the user currently connected to your app is the owner, or is joined to the
album:

- With [`albums.get`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums/get.md.txt) using the relevant `albumId`.
- With [`albums.list`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums/list.md.txt), if there are media items in the album.
- With [`sharedAlbums.list`](https://developers.google.com/photos/library/legacy/reference/rest/v1/sharedAlbums/list.md.txt), which returns all shared albums the user is joined to or owns. To retrieve only the albums your app has created, use the [`excludeNonAppCreatedData`](https://developers.google.com/photos/library/legacy/guides/list.md.txt#listappdata) parameter.
- With [`sharedAlbums.get`](https://developers.google.com/photos/library/legacy/reference/rest/v1/sharedAlbums/get.md.txt) using a share token.

If the user currently connected to your app is not joined to the album, you can
retrieve a shared album's details with
[`sharedAlbums.get`](https://developers.google.com/photos/library/legacy/reference/rest/v1/sharedAlbums/get.md.txt) using a
valid share token.

### Example request

### REST

Here is a request to get an album by its `shareToken`:

```
GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token
```

If the request is successful, it returns the shared
[`album`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#resource-album) details.

### Java

```java
try {
  // Get a shared album from its share token
  Album sharedAlbum = photosLibraryClient.getSharedAlbum(shareToken);

  String id = sharedAlbum.getId();
  String title = sharedAlbum.getTitle();
  // ...

} catch (ApiException e) {
  // Handle error
}
```

### PHP

```php
try {
    // Get the album from a share token
    $album = $photosLibraryClient->getSharedAlbum($shareToken);

    // Get some properties of an album
    $productUrl = $album->getProductUrl();
    $title = $album->getTitle();

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}
```

## Joining a shared album

Your app can join a shared album on behalf of a user with the album's share
token. To do so, the following conditions must be true:

- Your app has [created and shared](https://developers.google.com/photos/library/legacy/guides/share-media.md.txt#sharing-album) the album.
- The user you want to join to the album isn't its owner. That is, the `isOwned` field in the album's [`shareInfo`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#Album.ShareInfo) is false.
- The share token is valid.
- The `isJoinable` field in the album's `shareInfo` is true.

> [!CAUTION]
> **Caution:** After your app has shared an album, its owner can turn off link sharing or unshare the album in the Google Photos app. If this happens, the album's share token will be invalidated, its `isJoinable` field will be false, and your app won't be able to join users to it.

### REST

Here is a POST request header to join a shared album:

```
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join
Content-type: application/json
Authorization: Bearer oauth2-token
```

In the request body, specify the `shareToken`.

```restructuredtext
{
  "shareToken": "share-token"
}
```

The POST request returns the shared [`album`](https://developers.google.com/photos/library/legacy/reference/rest/v1/albums.md.txt#Album)
your app joined on behalf of the user.

### Java

```java
try {
  // Join the shared album using the share token obtained when sharing the album
  // If this call is not successful, an exception is raised
  JoinSharedAlbumResponse response = photosLibraryClient.joinSharedAlbum(shareToken);
  Album joinedAlbum = response.getAlbum();
} catch (ApiException e) {
  // Handle error
}
```

### PHP

```php
try {
    $response = $photosLibraryClient->joinSharedAlbum($shareToken);
    // Join the shared album using the share token obtained when sharing the album
    // If this call is not successful, an exception is raised
    $joinedAlbum = $response->getAlbum();
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}
```

## Leaving a shared album

Your app can leave a shared album on behalf of a user, using the album's share
token. To do so, the following conditions must be true:

- Your app has created and shared the album.
- The user is currently joined to the album. That is, the `isJoined` field in the album's `shareInfo` is true.
- The user connected to your app is not the owner of the album. That is, the `isOwned` field in the album's `shareInfo` is false.

### REST

Here is a POST request header to leave a shared album:

```
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave
Content-type: application/json
Authorization: Bearer oauth2-token
```

In the request body, specify the `shareToken`.

```restructuredtext
{
  "shareToken": "share-token"
}
```

If the request was successful, it returns an empty response with an HTTP
success status code. If the request was not successful, it returns an HTTP
error status code with an error message.

### Java

```java
try {
  // Leave a shared album using its share token
  // If this call is not successful, an exception is raised
  photosLibraryClient.leaveSharedAlbum(shareToken);
} catch (ApiException e) {
  // Handle error
}
```

### PHP

```php
try {
    // Leave the shared album using the share token obtained when sharing the album
    // If this call is not successful, an exception is raised
    $photosLibraryClient->leaveSharedAlbum($shareToken);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}
```

## Shared media item properties

[Media items](https://developers.google.com/photos/library/legacy/reference/rest/v1/mediaItems.md.txt) that belong to
albums shared by your app contain an additional property,
[`contributorInfo`](https://developers.google.com/photos/library/legacy/reference/rest/v1/mediaItems.md.txt#ContributorInfo).
This property is only included when [listing the
contents](https://developers.google.com/photos/library/legacy/guides/list#listing-album-contents) of a shared album.

The `contributorInfo` property includes the name of the user who added the media
item to the album, and a
[base URL](https://developers.google.com/photos/library/legacy/guides/access-media-items.md.txt#base-urls) to their profile
image.

Here's an example:

```
{
  "id: "media-item-id",
  ...,
  "mediaMetadata": {
    ...
  }
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters",
    "displayName": "name-of-user"
  }
}
```

> [!NOTE]
> **Note:** The `contributorInfo` property is only returned if the user has granted access to the `photoslibrary.sharing` scope.