Power Automate API - Connection

A Power Automate connection is created once in the Dashboard and used in services as self.microsoft.power_platform[name]. This page covers the connection form, how the connection uses the credentials, and the methods that are not tied to flows or runs - invoke with its four HTTP shorthands, and ping.

Dashboard fields

Under Cloud → Microsoft → Power Automate:

Every flow and run method works within the environment named here. A second environment needs a second connection.

What the app registration needs

An admin does two things once:

1. Adds the Flows.Read.All and Flows.Manage.All permissions of the Power Automate API, listed as Flow Service under API permissions, and consents to them for the tenant
2. Registers the app registration with Power Platform and gives it access to the environment the flows are in, which is done from an administrator's own sign-in, as an app registration cannot register itself

Tokens

The connection signs in with the client credentials grant - it posts the client ID and secret to https://login.microsoftonline.com/<tenant ID>/oauth2/v2.0/token and gets a token back, with the scope https://service.flow.microsoft.com/.default.

The token is obtained the first time it is needed, kept, and replaced a minute before it would expire. When Power Automate rejects a token anyway - for instance, the secret was rotated - the connection gets a new one and repeats the request once. Services never see a token.

trigger_url is the one method that sends no token, the callback URL it posts to carries its own signature instead.

invoke

conn.invoke(method, path, params=None, data=None)

Calls any endpoint of the Power Automate API with the connection's token, for the parts of the API that have no method of their own.

Returns the parsed JSON response, or nothing when the endpoint returned no body. A status code outside the success range for the method raises an exception with the code and the response text.

The flow and run methods all use one environment, the one in the connection form. invoke is how a service reaches beyond it, e.g. to list the environments the app registration can see:

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import Service

class ListEnvironments(Service):

    def handle(self):

        conn = self.microsoft.power_platform['Zato Power Automate']

        response = conn.invoke('GET', '/providers/Microsoft.ProcessSimple/environments')

        names = []
        for environment in response['value']:
            names.append(environment['properties']['displayName'])

        self.response.payload = {'environments': names}

{"environments": ["Contoso (default)", "Contoso Finance"]}

conn.get(path, params), conn.post(path, data, params), conn.patch(path, data, params) and conn.delete(path, params) are the same call with the method filled in.

ping

conn.ping()

Confirms the connection works by obtaining a token and listing the flows in the environment. The Ping button in the Dashboard calls it, and a service can too. Returns nothing, raises an exception when the token or the listing fails, and logs how many flows it found.

# -*- coding: utf-8 -*-

# Zato
from zato.server.service import Service

class Ping(Service):

    def handle(self):

        conn = self.microsoft.power_platform['Zato Power Automate']
        conn.ping()

        self.response.payload = {'connection': conn.name}

See also

Learn more