# Configure your app for the Ambient API

To start using the Ambient API, configure your project by enabling the api in
the Google API Console and setting up an OAuth 2.0 client ID. The Ambient API uses
[OAuth 2.0 for TV and Limited-Input Device
Applications](https://developers.google.com/identity/protocols/oauth2/limited-input-device).

Your application interacts with the Ambient API on behalf of a the Ambient API
user. The user authorizes these API requests using the [OAuth
2.0](https://developers.google.com/identity/protocols/OAuth2) protocol.

The OAuth 2.0 client ID allows your application users to sign in, authenticate,
and thereby use the Ambient API. The Ambient API don't support service accounts;
to use these APIs, users must be signed in to a valid Google Account.

## Configure your app

First enable the API, then request an OAuth 2.0 client ID.

### Enable the API

Before you can use the Ambient API, you must enable it in your project.

1. Go to the [Google API Console](https://console.developers.google.com/apis/library).
2. From the menu bar, select a project or create a new project.
3. To open one of the Google Photos APIs, from the Navigation menu, select **APIs \& Services \> Library**.
4. Search for "Ambient API". Select the Ambient API and click **Enable**.

### Request an OAuth 2.0 client ID

Follow these steps to request an OAuth client ID and configure it for your
application. The Ambient API uses [OAuth 2.0 for TV and Limited-Input Device
Applications](https://developers.google.com/identity/protocols/oauth2/limited-input-device).

1. Go to the [Google API Console](https://console.developers.google.com/apis/library) and select your project.
2. From the menu, select **APIs \& Services \> Credentials**.
3. On the **Credentials** page, click **Create Credentials \> OAuth client ID**.

   > [!NOTE]
   > **Note:** If you're setting up a new project, you may be prompted to configure your project's consent screen.

4. Select your **Application type** . In this example, the application type is
   **TVs and Limited Input devices**.

5. Provide a name for your OAuth 2.0 client and click **Create**.

6. From the resulting OAuth client dialog, copy the following:

   - Client ID
   - Client secret

Your app can access the enabled Google APIs using these values.

Before you can launch a public application that accesses the Ambient API, your
app must be reviewed by Google. An "Unverified app" message appears on the
screen when you test your application, until it is
[verified](https://support.google.com/cloud/answer/7454865).

After you've configured your app you're ready to get started. You can explore
the following resources, or read on about the [streamlined authentication
flow](https://developers.google.com/photos/ambient/guides/configure-your-app#streamlined-flow) for the Ambient API.

- [Create and manage devices](https://developers.google.com/photos/ambient/guides/devices)
- [List and retrieve media items](https://developers.google.com/photos/ambient/guides/media-items)

## Changing your client ID

Resources created through any of the Google Photos APIs can only be accessed or
modified using the original client ID used to create them. For example, if you
create a `session` in the Picker API with a specific client ID and later change
that client ID in your app, your app will lose access to any API resources
created with the previous client ID.

Plan carefully and choose the correct client ID type for the Photos API you are
using. Only change your client ID if absolutely necessary to avoid access
issues.

## Streamlined authentication flow for the Ambient API

The standard Ambient API authentication flow requires your users to scan 2 QR
codes:

- A 1st to sign in to their Google Account (if they are not signed in already).
- A 2nd that links to the newly created Ambient device in their Google Photos account where they can select media items to display.

The streamlined flow lets you provide a single QR code to your users by passing
the additional `state` parameter with your initial authentication call.

When [requesting device and user codes as part of OAuth for limited input
devices](https://developers.google.com/identity/protocols/oauth2/limited-input-device#step-1:-request-device-and-user-codes),
include the additional `state` parameter with your request. Add the following to
the `state` parameter:

| Parameters ||
|---|---|
| `https://developers.google.com/photos/ambient/reference/rest/v1/devices/create#body.QUERY_PARAMETERS.request_id` | `string` Required. A client-provided unique identifier for this request. This is used to mitigate resource duplication in the event of a network failure. This ID must have the format of a UUID (version 4) string and follow these requirements: - Must not contain any sensitive identifying information about the user. - Must contain 32 hexadecimal characters divided into five groups separated by hyphens, in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (or 8-4-4-4-12). |
| `https://developers.google.com/photos/ambient/reference/rest/v1/devices#AmbientDevice.FIELDS.display_name` | `string` Optional. A user-defined display name for this device. This will be visible to users from the Google Photos app settings but only editable through this API. Valid display names must have between 1 and 100 characters (inclusive). |

For example, see the following code block:

        const response = await fetch("https://oauth2.googleapis.com/device/code", {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                client_id: config.clientId,
                scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
                state: JSON.stringify({
                    'requestId': requestId,
                    'displayName': "My Device"
                })
            })
        });

A successful response will include a `user_code` and a `verification_url`, which
you show to the user (most likely as a QR code) so they can navigate there on a
separate device. By including the `state` parameter, when you later call
`createDevice` with the Ambient API, you can skip presenting the `settingsUri`
in a second QR code, as the last step in the OAuth flow will automatically
redirect to this location.

For complete details we've included a more thorough explanation. You can also
review the code in our [sample app](https://developers.google.com/photos/ambient/samples), for an example of
using the `state` parameter as part of OAuth for limited input devices with the
Ambient API.

#### Details about the streamlined authentication flow

To fully understand the streamlined OAuth flow for the Ambient API, it helps to
understand both the OAuth 2.0 for TV and Limited-Input Device Applications flow
as well as the standard Ambient API flow. Here are the steps for each flow.

**OAuth 2.0 for TV and Limited-Input Device Applications:**

1. Your application sends a request to Google's authorization server that identifies the scopes that your application will request permission to access.
2. The server responds with several pieces of information used in subsequent steps, such as a device code and a user code.
3. You display information that the user can enter on a separate device to authorize your app.
4. Your application starts polling Google's authorization server to determine whether the user has authorized your app.
5. The user switches to a device with richer input capabilities, launches a web browser, navigates to the URL displayed in step 3 and enters a code that is also displayed in step 3. The user can then grant (or deny) access to your application.
6. The next response to your polling request contains the tokens your app needs to authorize requests on the user's behalf. (If the user refused access to your application, the response does not contain tokens.)

**Ambient API flow:**

1. Check for an existing OAuth token, and either refresh the token or request a new one.
2. After obtaining an OAuth token, create a new device.
3. Display the `settingsUri` to the user, and begin to poll the device until `mediaSourcesSet` returns true.
4. The user navigates to the `settingsUri` and selects the photos they want to share with your application.
5. Once `mediaSourcesSet` returns true, retrieve the list of `mediaItems`.
6. Now you can begin your slideshow or other ambient experience.

Both flows include a step where you display a URL to your user, and your user
navigates there on their richer input device. By including the `state` parameter
in your initial OAuth call, you can avoid the second URL you have to display.

This works because the last step of the OAuth 2.0 for TV and Limited-Input
Device Applications flow normally redirects your user to a page that says "You
can now return to your device." By including the state parameter, the last step
of the flow will now try to redirect you to the `settingsUri`. Your app will
still receive an OAuth token. You should use this token to call `createDevice`
using the same `requestId`. Once a device with the same ID has been created, the
initial OAuth flow will successfully redirect your user to the correct page on
the rich device within the Photos app.

Remember the following points:

- It's still a good idea to display the `settingsUri` in case there are any issues with authentication.
- You can still use the `settingsUri` in other cases, such as when a user wants to update their photo selection.