# ARCore Cloud Anchor Management API

Manage Cloud Anchors outside of your ARCore app using the ARCore Cloud Anchor
Management API.

## Getting started

- [Authorization](https://developers.google.com/ar/develop/cloud-anchors/management-api#authorization)
- [Generate an OAuth2 token](https://developers.google.com/ar/develop/cloud-anchors/management-api#generate-token)

## Example operations

- [List all Cloud Anchors](https://developers.google.com/ar/develop/cloud-anchors/management-api#list-anchors)
- [Update a Cloud Anchor's time to live to the maximum time allowed](https://developers.google.com/ar/develop/cloud-anchors/management-api#update-ttl)
- [Delete Cloud Anchors](https://developers.google.com/ar/develop/cloud-anchors/management-api#delete-anchors)

## Authorization

Create a service account key in the
[Google Cloud Platform console](https://console.cloud.google.com) and generate
an OAuth2 token to authorize Cloud Anchor management API calls.

1. In the navigation menu of the
   [Google Cloud Platform console](https://console.cloud.google.com), go to
   **APIs \& Services** \> **Credentials**.

2. Select the desired project, then click **Create Credentials** \> **Service
   account**.

3. Under **Service account details** , type a name for the new account, then
   click **Create**.

4. On the **Service account permissions** page, go to the **Select a role**
   dropdown. Select **Service Accounts** \> **Service Account Token Creator** ,
   then click **Continue**.

5. On the **Grant users access to this service account** page, click **Done** .
   This takes you back to **APIs \& Services** \> **Credentials**.

6. On the **Credentials** page, scroll down to the **Service Accounts** section
   and click the name of the account you just created.

7. On the **Service account details** page, scroll down to the **Keys** section
   and select **Add Key** \> **Create new key**.

8. Select **JSON** as the key type and click **Create**. This downloads a JSON
   file containing the private key to your machine. Store the downloaded JSON
   key file in a secure location.

   > [!NOTE]
   > **Note:** This file contains a private key which must not be exposed to the public. Do **not** commit it to public source code repositories like GitHub.

## Generate an OAuth2 token

`arcore.management` is the OAuth scope for the Cloud Anchors Management API. By
default, oauth2l works on a token cache. The `fetch` command retrieves the same
token. Use [oauth2l](https://github.com/google/oauth2l) to generate an OAuth2
token for authorization:

    oauth2l fetch --json creds.json arcore.management

To generate a new token, add a `--cache=""` option to the `fetch`
command.

    oauth2l fetch --cache="" --json creds.json arcore.management

Alternatively, call `oauth2l reset` and call the `fetch` command again.

    oauth2l reset
    oauth2l fetch --json creds.json arcore.management

## List all Cloud Anchors

Get the first page of Cloud Anchors, optionally sorted by `expire_time`,
`create_time`, or `last_localize_time`.

Request:

    export BEARER_TOKEN=`(oauth2l fetch --json creds.json arcore.management)`
    curl -H "Authorization: Bearer $BEARER_TOKEN" \
       "https://arcore.googleapis.com/v1beta2/management/anchors?page_size=50&order_by=last_localize_time%20desc"

Response:

    {
      "anchors": [
        {
          "name": "anchors/ua-a1cc84e4f11b1287d289646811bf54d1",
          "createTime": "...",
          "expireTime": "...",
          "lastLocalizeTime": "...",
          "maximumExpireTime": "..."
        },
       ...
        {
          "name": "anchors/ua-41a3d0233471917875159f6f3c25ea0e",
          "createTime": "...",
          "expireTime": "...",
          "lastLocalizeTime": "...",
          "maximumExpireTime": "..."
        }
      ],
      nextPageToken: "some-long-string"
    }

If the response comes back with a `nextPageToken`, there are more anchors to
list. Use the `next_page_token` query parameter on the next request to retrieve
the next set of results.

Request:

    curl -H "Authorization: Bearer $BEARER_TOKEN" \
       "https://arcore.googleapis.com/v1beta2/management/anchors?page_size=50&order_by=last_localize_time%20desc&next_page_token=your-next-page-token-here"

When using `next_page_token`, `page_size` and `order_by` must be consistent
across requests. `page_size` defaults to `1000` and `order_by` defaults to
`expire_time_desc`.

## Update a Cloud Anchor's time to live to the maximum time allowed

Request a single Cloud Anchor to query its `lastLocalizeTime` and
`maximumExpireTime`.

Request:

    export BEARER_TOKEN=`(oauth2l fetch --json creds.json arcore.management)`
    curl -H "Authorization: Bearer $BEARER_TOKEN" \
       "https://arcore.googleapis.com/v1beta2/management/anchors/your-anchor-id-here"

Response:

    {
      "name": "anchors/ua-f21be53fd8ea57f0169c69fbf827f6b7",
      "createTime": "2020-06-29T21:00:00Z",
      "expireTime": "2020-08-28T22:00:00Z",
      "lastLocalizeTime": "2020-06-29T21:00:00Z",
      "maximumExpireTime": "2021-06-29T21:00:00Z"
    }

Once you have the anchor, update its `expireTime` to its `maximumExpireTime`.

Request:

    curl -H "Authorization: Bearer $BEARER_TOKEN" -H "Content-Type: application/json" -X "PATCH" \
       "https://arcore.googleapis.com/v1beta2/management/anchors/your-anchor-id-here?updateMask=expire_time" \
        -d '{ expireTime: "2021-06-29T21:00:00Z" }'

Response:

    {
      "name": "anchors/ua-f21be53fd8ea57f0169c69fbf827f6b7",
      "createTime": "2020-06-29T21:00:00Z",
      "expireTime": "2021-06-29T21:00:00Z",
      "lastLocalizeTime": "2020-06-29T21:00:00Z",
      "maximumExpireTime": "2021-06-29T21:00:00Z"
    }

## Delete Cloud Anchors

Delete a single Cloud Anchor:

    export BEARER_TOKEN=`(oauth2l fetch --json creds.json arcore.management)`
    curl -H "Authorization: Bearer $BEARER_TOKEN" -X "DELETE" \
       "https://arcore.googleapis.com/v1beta2/management/anchors/your-anchor-id-here"

Delete a batch of Cloud Anchors:

    export BEARER_TOKEN=`(oauth2l fetch --json creds.json arcore.management)`
    curl -H "Authorization: Bearer $BEARER_TOKEN" -H "Content-Type: application/json" -X "POST" \
       "https://arcore.googleapis.com/v1beta2/management/anchors:batchDelete" \
        -d '{ names: [ "anchors/your-anchor-id-here", "anchors/your-anchor-id-here" ]}'