# Integration Guide

## Obtain Private Key

### Using Onboarding Interface

To integrate with the API, you must create a Google Cloud Project. After that
create a service account and obtain a private key. To get started, click the
following button:

Create Service Account

### Manually Generating Key

If the above interface fails, please try the following:

1. Go to [Google Cloud Console](https://console.cloud.google.com/).
2. Choose the project using which the API will be accessed.
3. Under the IAM \& admin menu on the left, find service accounts and create a new Service Account which will be the owner of the project.
4. Once the service account is created, you should receive a private key.

## Whitelist Service Account

Once you have created a service account:

1. Reach out to GTAF team at [mdp-support@google.com](mailto:mdp-support@google.com) with a Google account which is the owner of the project. We will whitelist the Google account to access the Mobile Data Plan Sharing API endpoints.
2. Associate service account with the carrier on [Google ISP
   Portal](https://isp.google.com/). The carrier can make this association by going to [API Access](https://isp.google.com/api_access/).

## Enable Library

Once the whitelisting has been done:

1. Visit [Google Cloud Console](https://console.cloud.google.com).
2. Make sure you've selected the correct project in the dropdown on the top menu bar.
3. Enable [Mobile Data Plan Sharing API](https://console.cloud.google.com/apis/library/mobiledataplansharing.googleapis.com/) in the [API Library](https://console.developers.google.com/apis/library).
4. Enable [Preprod Mobile Data Plan Sharing API](https://console.cloud.google.com/apis/library/preprod-mobiledataplansharing.googleapis.com/) in the [API Library](https://console.developers.google.com/apis/library).

## Test API Access

To test your access to Google side methods:

1. Install [`oauth2l`](https://github.com/google/oauth2l).
2. Obtain an access token for your service account as follows.
   `your-service-account-key-file.json` is a key file of your service account.

       > oauth2l fetch --json your-service-account-key-file.json dataplansharing

   Note that the access token expires in about one hour. Before you run above
   command again for a new access token, run `oauth2l reset` to clear the local
   cache.
3. Issue test calls as follows. `YOUR-ASN` must be one of the ASNs you send
   to us when we configured GTAF during the integration process.
   `ACCESS-TOKEN-OBTAINED` is the output of above `oauth2l fetch` command.
   PLAN_STATUS is the
   [PlanStatus](https://developers.google.com/mobile-data-plan/reference/rest/v1/operators.clients.users.planStatus#PlanStatus)
   request body you are looking to send to GTAF.

       > url_domain="mobiledataplansharing.googleapis.com"
       > url_path="v1/operators/YOUR-ASN/clients/mobiledataplan/users/USER_KEY/planStatus"
       > curl -H "Content-Type: application/json" \
              -d 'PLAN_STATUS' \
              -X POST "https://$url_domain/$url_path?access_token=ACCESS-TOKEN-OBTAINED"

## Programmatic API calls

Follow the
[instructions](https://developers.google.com/identity/protocols/OAuth2ServiceAccount#authorizingrequests)
to make authorized calls to Google side methods, with the following OAuth scope:

    https://www.googleapis.com/auth/dataplansharing

## Sharing Project Ownership

While the initial set up involves a single Google account, it is a good idea to
for a group of authorized users to have ownership of the project. On [Google
Cloud Console](https://console.cloud.google.com/), under IAM \& admin menu, you
can add new members (including Google groups account) to be owners of the
project.