# Partner API

## Overview

The Partner API allows you to programmatically manage subscribers, reports, and other platform resources. All API calls require authentication via an access token obtained from the login endpoint.

## Getting Started

To authenticate with the Partner API, you will need:

* **`PROJECT_ID`** — your project identifier, visible under the project name in the Management Console.
* **`PRIVATE_KEY`** — your Partner API password, found in **Settings > General** in the Management Console (masked by default — click the eye icon to reveal it).

See [General project settings](https://pango.gitbook.io/paas/console-details/project-settings/general) for details.

1. Call `POST /partner/login` with your project credentials

   ```bash
   curl $BASE_URL/partner/login \
       -H "Content-Type: application/x-www-form-urlencoded" \
       -d "login=$PROJECT_ID&password=$PRIVATE_KEY"
   ```

   Example response:

   ```json
   {
       "result": "OK",
       "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
       "create_time": 1700000000,
       "expire_time": 1700003600
   }
   ```

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Use <code>expire_time</code> to track when to renew the access token. As a rule of thumb, trigger renewal before <code>expire_time - 1 minute</code> to avoid expired-token errors.</p></div>
2. Extract the `access_token` from the response
3. Include the token as a Bearer token in subsequent requests

   ```bash
   curl -X POST "$BASE_URL/partner/v2/getUser" \
       -H 'accept: application/json'\
       -H "authorization: Bearer $ACCESS_TOKEN"\
       -H 'content-type: application/json' \
       -d '{"username": "'"$USERNAME"'"}'
   ```

   Example response:

   ```json
   {
       "result": "OK",
       "user": {
           "id": 0,
           "username": "string",
           "auth_method": "string",
           "enabled": false,
           "extra": {
               "country": "string",
               "language": "string"
           }
       }
   }
   ```

{% hint style="info" %}
**Default values are treated as missing fields.** The API considers default values (0 for numbers, empty string for strings) equivalent to omitting the field entirely. For example, these requests are all parsed identically:

* `{"user_id": 0}`
* `{"username": ""}`
* `{}`

This means `user_id=0` is not a valid user ID, it will be interpreted as if no user ID was provided.
{% endhint %}

## Resources

* [Partner API documentation](https://apidocs.pango-cloud.com/partner2.html)