Scopes and permissions

When a user connects an account, the platform asks them to approve a list of permissions. By default Pozy asks for everything it supports on that platform, so the account can post, read analytics, answer comments and handle messages. If your product only publishes, you can ask for less. A shorter consent screen is easier to approve, and some platforms review apps by what they request.

Two different things are called permissions in Pozy:

This page is about the first.

#Request fewer areas

Pass scopes with a comma-separated list of areas on the connect call:

curl "https://api.pozy.ai/v1/connect/linkedin?profileId=6650c1f2a9e4b7d3c8a1f0e2&scopes=posting,analytics&redirect_url=https://app.example.com/connected" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/connect/linkedin?profileId=6650c1f2a9e4b7d3c8a1f0e2&scopes=posting,analytics&redirect_url=https:%2F%2Fapp.example.com%2Fconnected", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

resp = requests.get(
    "https://api.pozy.ai/v1/connect/linkedin",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "profileId": "6650c1f2a9e4b7d3c8a1f0e2",
        "scopes": "posting,analytics",
        "redirect_url": "https://app.example.com/connected",
    },
    timeout=30,
)

The consent screen then lists only those areas, plus what every connection needs: the user's identity, token refresh, and the list of Pages, organizations or channels to pick from.

#Areas

The exact platform scopes behind each area are listed per platform in the platforms field of GET /v1/connect/oauth-apps.

#Which platforms accept scopes

Sending scopes to a platform that rejects it, or an unknown area, returns 400 invalid_field_value with param: scopes.

#Google and Microsoft

Google and Microsoft accounts require scopes, with their own areas:

curl "https://api.pozy.ai/v1/connect/google?profileId=6650c1f2a9e4b7d3c8a1f0e2&scopes=email,calendar&loginHint=ana@acme.com" \
  -H "Authorization: Bearer $POZY_API_KEY"

Areas only accumulate. Connecting the same mailbox again with more areas widens the same account and keeps its accountId. Leaving an area out of a reconnect does not remove it: to drop one, disconnect the account and connect it again. See Email, calendar & files.

#Ask for less, carefully

Ask for the areas you will use in the next few months, not just today. A second consent screen is a point where users drop off.

#See what was granted

Users can untick permissions on some consent screens. What you asked for and what you got can differ. Account health shows the result:

{
  "permissions": {
    "posting": [{ "scope": "w_member_social", "granted": true, "required": true }],
    "analytics": [{ "scope": "r_organization_social", "granted": false, "required": true }],
    "canPost": true,
    "canFetchAnalytics": false,
    "missingRequired": ["r_organization_social"]
  }
}

canPost and canFetchAnalytics are the two flags to check before you offer a feature for an account. GET /v1/accounts/health returns them for every account at once.

#When a permission is missing

#Webhook events

#Endpoints