# Create and manage devices

This guide covers how to create, manage, and delete devices. Proper device
management helps create a smooth user experience and efficient use of the
Ambient API.

## Create Devices

After a user has successfully authenticated using the [OAuth 2.0 for TV and
Limited-Input Device Applications](https://developers.google.com/identity/protocols/oauth2/limited-input-device)
flow, create a device in their Google Photos account.

When your app successfully creates a device using the `devices.create` method,
the Ambient API returns an `AmbientDevice` object that includes a
Google-generated `id`. Securely store this `id` and associate it with your
users.

> [!IMPORTANT]
> **Important:** Save the `id`. If you don't save the Google-generated `id`, you won't be able to retrieve or manage a device later. This can lead to orphaned devices in your users' Google Photos accounts, which can't be accessed or cleaned up by your application.

### Streamlined Device Creation with OAuth

The Ambient API offers a streamlined OAuth flow that can create a device
simultaneously with user authentication. By passing the additional `state`
parameter in your initial OAuth request, you can link the device creation
process directly to the user's sign-in flow, simplifying the user experience by
reducing the number of QR codes they need to scan.

For more details and an example, see the [Streamlined authentication flow for
the Ambient API](https://developers.google.com/photos/ambient/guides/configure-your-app#streamlined-flow) guide.

## Device Limits

Your application can create up to *100 devices per user* . If this limit is
exceeded, the API returns a `RESOURCE_EXHAUSTED` error.

## Manage Devices

Once a device is created and linked to a user's Google Photos account, you might
need to manage its lifecycle.

### Retrieve Devices

To retrieve information about a specific device, use the `devices.get` method
with its unique `id`. This is useful for checking the device's status, such as
whether `mediaSourcesSet` is true.

### Update Devices

You can update certain properties of an existing device, such as its display
name, using the `devices.patch` method. This allows users to personalize their
devices and makes them easier to identify within Google Photos.

> [!NOTE]
> **Note:** A good practice is to offer the user the opportunity to name their device before creating it. This makes it much easier for the user to recognize their device when picking media items in their Google Photos account.

### Delete Devices

Implement a strategy for deleting devices for proper cleanup and user control.
You can delete a device using the `devices.delete` method.

Consider the following scenarios for deleting devices:

- **User disconnection**: If a user disconnects your application from their Google Photos account, you should delete the corresponding device.
- **Orphaned Devices** : If you lose track of a `id` but still have the `requestId` that was used during creation, you can use the `requestId` with `devices.delete` to remove an orphaned device. This helps prevent accidental duplicates and keeps the user's account clean.

## Important Considerations and Best Practices

- **Device lifecycle and user authorization:** You'll need to manage the lifecycle of devices and user authorization tokens. Consider how long devices remain active and how you'll handle token refreshes or re-authorization if a device becomes inactive or its token expires.
- **Error Handling:** Implement robust error handling for all device-related API calls. Be prepared for scenarios like:
  - `NOT_FOUND`: If a device doesn't exist or isn't owned by the user.
  - `RESOURCE_EXHAUSTED`: If you exceed the device limit.
  - `ALREADY_EXISTS`: If you try to create a device with a `requestId` that already exists.

## Next Steps

- **Sample Application:** Our [sample application](https://developers.google.com/photos/ambient/samples) includes an example of creating a device and working with the response data. Check out the `createDevice` function for more info.
- **Reference Documentation:** Review the comprehensive [reference docs on devices](https://developers.google.com/photos/ambient/reference/rest/v1/devices) for detailed information on all available methods, request and response parameters, and error codes.
- **List and retrieve media items:** Once you've created and managed your devices, learn how to [list and retrieve media items](https://developers.google.com/photos/ambient/guides/media-items) to display on them.