Permissions API

Before using any of the Home APIs, the app must have permission to access devices in the user's home, referred to in the API as the structure.

The Home APIs uses OAuth 2.0 to grant access to devices in the structure. OAuth allows a user to grant permission to an app or service without having to expose their login credentials. With the Permissions API, the user can, using their Google Account, grant Home APIs apps access to devices in their home.

Using the Permissions API involves a number of steps in your app, Google Cloud, and the Developer Console:

1. Set up OAuth in Google Cloud
   1. Sign the app
   2. Set up the OAuth consent screen
   3. Register the app and create credentials
2. Integrate the Permissions API
   1. Check for permissions
   2. Request permissions
3. Grant permissions
   1. Change permissions
   2. Revoke permissions

Set up OAuth in Google Cloud

If you already have a verified OAuth client, you can use that client without setting up a new one. For more information, refer to If you have an existing OAuth client.

Sign the app

1. Generate an OAuth key by running the app in Android Studio. When you run or debug an app in Android Studio, it automatically generates an OAuth key intended for development and debugging. See Android Studio: Sign your debug build for a complete explanation.

   Connect your mobile device to your local machine. Android Studio will list your connected devices by model number. Select your device from the list, then click Run project. This builds and installs the sample app on your mobile device.

   For more detailed instructions, see Run apps on a hardware device on the Android Developers site.

   Now stop the running app.

2. Get the OAuth certificate's SHA-1 fingerprint by following the instructions detailed in Setting up OAuth 2.0 / Native applications / Android on the Google Cloud Console Help site.

Set up the OAuth consent screen

1. In the Google Cloud console, go to the project selector dashboard and select the project that you want to use to create OAuth credentials.
2. Go to the APIs and Services page, and in the navigation menu and click Credentials.

3. If you haven't yet configured your consent screen for this Google Cloud project, the Configure consent screen button appears. In that case, configure your consent screen using the following procedure. Otherwise, move on to Register the app and create credentials.

   1. Click Configure consent screen. The OAuth consent screen page displays.
   2. Depending on your use case, select Internal or External, and then click Create. The OAuth consent screen pane displays.
   3. Enter information on the App information page according to the on-screen instructions, and then click Save and continue. The Scopes pane displays.
   4. You don't need to add any scopes, so click Save and continue. The Test users pane displays.
   5. If you want to add users to test access to your app, click Add users. The Add users pane displays. Test users have the privilege to grant permissions in your app.
   6. In the empty field, add one or more Google Account email addresses, and then click Add.
   7. Click Save and continue. The Summary pane displays.
   8. Review your OAuth consent screen information, and then click Back to dashboard.

See Setting up your OAuth consent screen on the Google Cloud Console Help site for full details.

Register the app and create credentials

To register the app for OAuth 2.0 and create OAuth credentials, follow the instructions provided in Setting up OAuth 2.0. You'll need to indicate the app type, which is native/Android app.

Add the SHA-1 fingerprint you got from signing the app to the OAuth client you set up on the Google Cloud console by following the instructions in Setting up OAuth 2.0 / Native applications on the Google Cloud Console Help site.

With your mobile device connected to your local machine, select your device from the list, then click Run project again to run it. For more detailed instructions, see Run apps on a hardware device on the Android Developers site.

Integrate the Permissions API

Users must grant permissions to your app in order to access devices within a given structure. To begin, make sure you have followed initialized the Home APIs. The homeManager instance from that step is used in all Permissions examples here.

First, register an ActivityResultCaller with the SDK. For example, this is how the sample app handles it:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    homeManager.registerActivityResultCallerForPermissions(this)
  }

Check for permissions

Prior to requesting permissions, we recommend you check to see whether the user of the app has already granted consent. To do so, call the hasPermissions() method of the Home instance to obtain a Flow of PermissionsState values:

val permissionsReadyState =
  homeManager.hasPermissions().collect { state ->
    state == PermissionsState.GRANTED ||
      state == PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ||
      state == PermissionsState.NOT_GRANTED
    when (permissionsReadyState) {
      PermissionsState.GRANTED -> println("Permissions granted, no need to request permissions")
      PermissionsState.PERMISSIONS_STATE_UNAVAILABLE ->
        println("Permissions state unavailable, request permissions")
      PermissionsState.NOT_GRANTED ->
        println("OAuth permission is enabled but not granted yet, request permissions")
      else ->
        throw IllegalStateException(
          "HomeClient.hasPermissions state should be PermissionsState.GRANTED or " +
            "PermissionsState.PERMISSIONS_STATE_UNAVAILABLE")
  }
}

If the check returns a PermissionsState of NOT_GRANTED or PERMISSIONS_STATE_UNAVAILABLE, you'll want to request permissions. If the check returns a PermissionsState of GRANTED but a subsequent call to structures() returns no structures, then the user has revoked access to the app through the GHA settings page, and you should request permissions. Otherwise, the user should already have access.

Request permissions

Permission must be granted to your app in order to access structures and devices within a given structure.

If the user has not already granted permissions, use the requestPermissions() method of the Home instance to launch the Permissions UI and process the result:

fun requestPermissions(scope: CoroutineScope, onShowSnackbar: (String) -> Unit) {
  scope.launch {
    val result =
      try {
        homeManager.requestPermissions()
      } catch (e: HomeException) {
        PermissionsResult(
          PermissionsResultStatus.ERROR,
          "Got HomeException with error: ${e.message}",
        )
      }
    when (result.status) {
      PermissionsResultStatus.SUCCESS -> {
        Log.i(TAG, "Permissions successfully granted.")
      }
      PermissionsResultStatus.CANCELLED -> {
        Log.i(TAG, "User cancelled Permissions flow.")
        onShowSnackbar("User cancelled Permissions flow")
      }
      else -> {
        Log.e(
          TAG,
          "Failed to grant permissions with error: ${result.status}, ${result.errorMessage}",
        )
        onShowSnackbar("Failed to grant permissions with error: ${result.errorMessage}")
      }
    }
  }
}

For the Permissions UI to properly launch, you must have already set up OAuth for your app.

Grant permissions

Now you should be able to run your app and have a user grant permissions. The type of users that can grant permission, and the device types that are available to grant permissions for, will differ depending on whether you have registered your app in the Developer Console.

Developer Console registration is required to publish an app using the Home APIs. It is not required to test and use the Home APIs. For access to the console registration feature, contact your Google Technical Account Manager (TAM).

If an app is not registered in the Developer Console, it will be in an unverified state. This is recommended for testing use of the Home APIs:

• Only users registered as test users in the OAuth console can grant permissions for the app. There is a limit of 100 test users for an unverified app.

• An unverified app will have access to devices of any device types that are supported by OAuth for the Home APIs (the list of device types in the Developer Console). All devices in a structure will be granted.

If an app is registered in the Developer Console and has been approved for access to one or more device types, and brand verification has been completed for OAuth, it will be in a verified state. This state is required for launching an app to production:

• Test user limits no longer apply. Any user can grant permission to the app.
• The user can only grant permission to the device types that were approved in the Developer Console.

Now that OAuth is set up, the app's call to requestPermissions() triggers the following dialogs:

1. The user is prompted to select the Google Account they want to use.
2. The user is prompted to select the structure they want to grant the app access to.
   1. For an unverified app, all device types supported by the Home APIs are available to the app.
   2. For a verified app, the user can grant permission to only the device types that have been approved in Developer Console.
   3. For sensitive device types that the app has access to manage, the user can restrict access on a per-device basis. For example, if a user has three locks, they can grant access to only one of those locks.

Once permission has been granted, the app can use the Home APIs to read the state of and control the devices in the structure. If the user doesn't grant permission to the app for a particular device type or sensitive device, the app won't be able to use the Home APIs to access, control, or automate it.

Change permissions

To grant permission to access devices in a different structure, the account picker can be launched to allow the user to pick the Google Account and structure to switch to. During this process, the user will be presented with the consent screen again, even if consent was granted previously.

This can be done by calling requestPermissions() again with the forceLaunch flag set to true:

homeManager.requestPermissions(forceLaunch=true)

Revoke permissions

Users can revoke previously-granted access:

1. Through the Google MyAccounts page > Data & privacy > Third-party apps & services. This will revoke the OAuth token that was issued when initial consent was granted, and will revoke access to any instance of the app that the user was using across all surfaces (phones) and structures.

2. Through the GHA > Settings > Linked Apps page. Clicking on settings in the GHA will take you to the Settings page. From there, click the Linked Apps tile which takes you to a page that looks similar to the consent screen. From this page the user can remove access to the app. The user can use this same page to change which device types or specific sensitive devices are accessible to the app.

3. Through the Linked Apps page directly on the web.

If you have an existing OAuth client

If you already have a verified OAuth client for a published app, you can use your existing OAuth client to test the Home APIs.

Developer Console registration is not required to test and use the Home APIs. However, you will still need an approved Developer Console registration to publish your app, even if you have a verified OAuth client from another integration.

The following considerations apply:

• There is a 100-user limit when using an existing OAuth client. For information about adding test users, refer to Set up the OAuth consent screen. Independent of OAuth verification, there is a Home APIs-imposed limit of 100 users who can grant permissions to your application. This limitation is lifted upon completion of Developer Console registration.

• Developer Console registration should be sent for approval when you are ready to restrict device-type grants through OAuth in preparation for updating your app with the Home APIs.

For Google Cloud apps that are still pending OAuth verification, users can't complete the OAuth flow until verification is complete. Attempts to grant permissions will fail with the following error:

Access blocked: <Project Name> has not completed the Google verification process.

OkGoogle permissions

The okGoogle command is a structure-level command and can be used to automate any device in the structure. However, a Home APIs app may not have access to every device. The following table describes how permissions are enforced in such cases.