> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials & Setup

> Create a Google Play service account, grant Play Console permissions, and save credentials in Appeeky

Google Play Connect uses a **service account JSON key** from Google Cloud. The same service account must be invited as a user in Play Console before it can access owned-app data.

<Warning>
  Do not create or share a normal Google API key for this integration. The credential is the service account JSON file.
</Warning>

***

## Required Google APIs

Enable these APIs in the Google Cloud project that will own the service account:

| API                                 | Required for                                                                  |
| ----------------------------------- | ----------------------------------------------------------------------------- |
| Google Play Android Developer API   | Reviews, review replies, releases, listings, subscriptions, one-time products |
| Google Play Developer Reporting API | Android vitals, crash rate, ANR rate, app quality metrics                     |
| Cloud Storage API                   | Play Console bulk CSV reports in the `gs://pubsite_prod_...` bucket           |

Official references:

<CardGroup cols={2}>
  <Card title="Android Publisher API" icon="google" href="https://developers.google.com/android-publisher/getting_started">
    Service account setup for Google Play Developer API.
  </Card>

  <Card title="Developer Reporting API" icon="chart-line" href="https://developers.google.com/play/developer/reporting/overview">
    Android vitals and quality reporting setup.
  </Card>
</CardGroup>

***

## Create the Service Account JSON

1. Open **Google Cloud Console > IAM & Admin > Service Accounts**.
2. Choose the Google Cloud project connected to Play Console, or create a new project.
3. Create a service account.
4. Open the service account.
5. Go to **Keys**.
6. Create a new key.
7. Select **JSON**.
8. Download the JSON file.

You do not need to grant broad IAM roles inside Google Cloud for Play Console access. The important access control happens in Play Console after the service account is invited there.

<Tip>
  If Google Cloud asks for a project IAM role during service account creation, a minimal viewer-style role is enough for creation flow. Play Console permissions decide which app data the API can access.
</Tip>

***

## Invite the Service Account in Play Console

Open **Play Console > Users and permissions**, then invite the service account email from the JSON file. The email looks like:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
appeeky@your-project.iam.gserviceaccount.com
```

Grant permissions based on the features the customer wants:

| Feature                                               | Play Console permission guidance                        |
| ----------------------------------------------------- | ------------------------------------------------------- |
| App list                                              | App information read access                             |
| Bulk reports                                          | Global `View app information and download bulk reports` |
| Store performance, installs, ratings, crashes reports | Same global bulk report permission                      |
| Financial reports                                     | Global `View financial data`                            |
| Review listing                                        | Review read access                                      |
| Review replies                                        | Review reply/manage access                              |
| Android vitals                                        | App quality / Android vitals access                     |
| Release tracks                                        | Release read or release management access               |
| Release updates                                       | Release management access                               |
| Store listing metadata                                | Store listing management access                         |
| Subscriptions and one-time products                   | Monetization product access                             |

For analytics dashboards, start with:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Global: View app information and download bulk reports
App: Android vitals / app quality access
```

Add write permissions only when the customer wants Appeeky to reply to reviews or update releases/listings.

***

## Connect Credentials

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.appeeky.com/v1/connect/google-play/credentials" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceAccountJson": {
      "type": "service_account",
      "project_id": "your-google-project",
      "private_key_id": "...",
      "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "client_email": "appeeky@your-project.iam.gserviceaccount.com",
      "client_id": "..."
    },
    "defaultPackageName": "com.example.app",
    "reportsBucket": "pubsite_prod_8701287375724464057"
  }'
```

| Field                | Required | Description                                          |
| -------------------- | -------- | ---------------------------------------------------- |
| `serviceAccountJson` | Yes      | Full JSON key downloaded from Google Cloud           |
| `defaultPackageName` | No       | Default app package for dashboards and tools         |
| `reportsBucket`      | No       | Required for report imports and analytics dashboards |

The API verifies credentials before saving. A successful response means Google accepted the service account and the account can access at least basic Play Console app data.

***

## Per-Request Credentials

Saved credentials are recommended. For testing, you can also pass credentials per request:

| Header                      | Description                     |
| --------------------------- | ------------------------------- |
| `X-GP-Service-Account-Json` | Full service account JSON       |
| `X-GP-Client-Email`         | Service account `client_email`  |
| `X-GP-Private-Key`          | Service account private key PEM |
| `X-GP-Private-Key-B64`      | Base64 private key alternative  |
| `X-GP-Project-Id`           | Optional project ID             |
| `X-GP-Client-Id`            | Optional client ID              |

Use saved credentials for production customers so background sync jobs can run without asking for headers on every request.

***

## Check Status

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/google-play/credentials/status" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
```

Example response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "connected": true,
    "serviceAccountEmail": "appee...@your-project.iam.gserviceaccount.com",
    "projectId": "your-google-project",
    "defaultPackageName": "com.example.app",
    "reportsBucket": "pubsite_prod_8701287375724464057",
    "analyticsSyncStatus": "pending",
    "lastSyncedAnalyticsDate": null
  }
}
```

***

## Delete Credentials

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X DELETE "https://api.appeeky.com/v1/connect/google-play/credentials" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
```

This removes the saved connection and deletes the encrypted credential from Appeeky.

***

## Troubleshooting

| Error                              | Meaning                                                             | Fix                                                                       |
| ---------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `GOOGLE_PLAY_CREDENTIALS_REQUIRED` | Missing service account JSON or private key fields                  | Send `serviceAccountJson`, or `clientEmail` + private key                 |
| Google OAuth error                 | The JSON key is malformed, revoked, or from the wrong project       | Create a new JSON key and retry                                           |
| App list is empty                  | Service account is authenticated but has no Play Console app access | Invite the service account in Play Console and grant app permissions      |
| Report listing fails               | Basic Play API access works, but GCS bulk report access is missing  | See [Report Exports](/docs/google-play-reports#storageobjectslist-denied) |

Permission changes in Play Console can take time to propagate. If setup looks correct, wait a few minutes and retry.