# Power Automate API - Connection

The Dashboard fields, how tokens are obtained and refreshed, invoke for endpoints without a method of their own, and ping.

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 {#dashboard-fields}

Under `Cloud → Microsoft → Power Automate`:

| Field | Value |
| --- | --- |
| Name | Any, used as `self.microsoft.power_platform[name]` - the examples on these pages use `Zato Power Automate` |
| Address | The Power Automate API, `https://api.flow.microsoft.com` for the public cloud, or the address your admin gives you for a national cloud |
| Tenant ID | The directory (tenant) ID of the app registration, from its overview page in the Azure portal |
| Client ID | The application (client) ID, from the same page |
| Client secret | A secret created under the app registration's Certificates and secrets |
| Environment ID | The Power Platform environment the flows are in, from `Environments` in the Power Platform admin center, e.g. `Default-98765432-5432-5432-5432-dcba98765432` |

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

## What the app registration needs {#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 {#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 {#invoke}

```python
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.

| Parameter | Type | Meaning |
| --- | --- | --- |
| `method` | str | `GET`, `POST`, `PATCH` or `DELETE` |
| `path` | str | The path after the address, e.g. `/providers/Microsoft.ProcessSimple/environments` |
| `params` | dict | Query string parameters, or none - `api-version` is `2016-11-01` unless given here |
| `data` | dict | The JSON body, or none |

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:

```python
# -*- 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}
```

```json
{"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 {#ping}

```python
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.

```python
# -*- 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 {#see-also}

- [Your first Power Automate integration](https://zato.io/docs/dev/examples/cloud/power-automate/tutorial.html) - Creating the app registration and the connection step by step
- [Power Automate API - Flows](https://zato.io/docs/dev/examples/cloud/power-automate/api/flows.html) - The flow methods, including trigger and trigger\_url
- [Power Automate API - Runs](https://zato.io/docs/dev/examples/cloud/power-automate/api/runs.html) - The run methods and the run statuses

## Learn more {#learn-more}

- [Development documentation](https://zato.io/docs/dev/) - Everything about writing services, in one place
- [Requests and responses](https://zato.io/docs/dev/request-response/) - What a service receives, what it returns and how to shape both
- [Integration examples](https://zato.io/docs/dev/examples/) - Ready-made code for the systems you are likely to connect to
- [IDE and debugging](https://zato.io/docs/dev/ide/) - Write services in the Dashboard or in your own editor
- [Data models](https://zato.io/docs/dev/model/) - Declare inputs and outputs and have them validated for you
- [In-depth API tutorial](https://zato.io/tutorials/main/01.html) - The full platform tutorial, from installation to production patterns