> For the complete documentation index, see [llms.txt](https://flowmate.gitbook.io/flowmate-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flowmate.gitbook.io/flowmate-documentation/using-the-flowmate-api/authentication-system.md).

# Authentication System

FlowMate’s authentication system can be used **independently** of the rest of the integration platform. This means you can let your customers connect their apps securely through the **Integration Center**, while you reuse the generated credentials within your own integration logic.

This approach is especially useful if:

* You only need a secure and standardized way to collect user credentials.
* You want to delegate authentication UI and flows to FlowMate.
* You want to support multiple types of authentication methods with minimal effort.

### Supported Authentication Types

FlowMate supports the following authentication types:

| Auth Type    | FlowMate Type            |
| ------------ | ------------------------ |
| Basic Auth   | `SIMPLE`                 |
| oAuth 2.0    | `OA2_AUTHORIZATION_CODE` |
| API Key      | `API_KEY`                |
| Session Auth | `SESSION_AUTH`           |

Each type is stored as a **secret** and can be accessed via the FlowMate Secrets API.

***

### Impersonate the User

The impersonate call provides a token that authorizes you to manage the users. This token must be included in subsequent API calls (such as starting flows) to authenticate your actions on behalf of the user. Use the `username` field to specify the external identifier of the user (the one passed by the customer).

`POST` `https://api.platform.openintegrationhub.com/impersonate`

**Request Body Example**

```json
{
  "username": "abc123"
}
```

**Response**

```json
{
  "token": "f9MPJQz6aRfQH4qVnkzUFbU3-4n-BAjiBXQKmED4_e15KK745Heq9KY2M7XknbGi-zO3XHF--OnbZUyqTHEO-qwXwzFX8K-isRZ2lclMzXDZiD_2DahQ1rfynbZHfn_VFi8VfHda5FiLfhcmxa20WL2TcPq82_lpgKN0nSTwCD4",
  "id": "62460554305401543e4e60c1"
}
```

### Retrieving Secrets

You can retrieve stored credentials via the Secrets API.

{% hint style="info" %}
You can only retrieve secrets if you are listed as an `owner` of that secret. To retrieve those secrets, you need to use the user token, which you obtain via the Impersonate Endpoint.
{% endhint %}

#### List All Secrets

**`GET`** `https://api.platform.openintegrationhub.com/secrets/`

**Example response:**

```json
{
  "data": [
    {
      "_id": "66761aedkf268b4d68470e27",
      "name": "demo.oih@gmail.com",
      "owners": [
        {
          "id": "634d07662ba257a7eb2373d6c",
          "type": "USER"
        }
      ],
      "type": "SIMPLE",
      "__t": "S_SIMPLE"
    }
  ]
}
```

#### Get a Specific Secret by ID

This endpoint returns the full secret object including the actual credentials (e.g., username/password, API key, access token).

{% hint style="info" %}
For OAuth 2.0 and Session Auth, calling this endpoint will automatically refresh the token (if necessary) and return a currently valid accessToken. This ensures that your integration always receives a fresh and usable token without handling token refresh logic manually.
{% endhint %}

**`GET`** `https://api.platform.openintegrationhub.com/secrets/{id}`

**Example response (Basic Auth):**

```json
{
    "data": {
        "value": {
            "username": "email@email.com",
            "passphrase": "thisisapassword"
        },
        "_id": "63861abbee268b4d71880e27",
        "name": "email@email.com",
        "owners": [
            {
                "id": "636d0762bd257a7eb2373d6c",
                "type": "USER"
            }
        ],
        "type": "SIMPLE",
        "encryptedFields": [],
        "__t": "S_SIMPLE",
        "createdAt": "2022-11-29T14:44:11.143Z",
        "updatedAt": "2022-11-29T14:44:11.143Z",
        "__v": 0
    }
}
```

### Secret Examples By Auth Type

#### Basic Auth (`SIMPLE`)

```json
"data": {
        "value": {
            "username": "email@email.com",
            "passphrase": "thisisapassword"
        },
```

#### API Key (`API_KEY`)

```json
    "data": {
        "value": {
            "key": "12345678910",
            "headerName": ""
        }
```

#### OAuth 2.0 (`OA2_AUTHORIZATION_CODE`)

This will include an OAuth token object:

```json
    "value": {
            "authClientId": "64************",
            "accessToken": "xo****************",
            "scope": "channels:read,chat:write,chat:write.public,calls:write,channels:history,groups:history,mpim:history,im:history",
            "expires": "33658-09-27T01:46:40+00:00",
            "externalId": "7d6********"
        },
```

#### Session Auth (`SESSION_AUTH`)

While the customer provides **input fields** (e.g. client credentials) to establish a session, **your integration should use the `accessToken`** for authentication.

```json
        "value": {
            "authClientId": "643*****",
            "accessToken": "pa*********",
            "inputFields": {
                "client_id": "pa*******",
                "client_secret": "pa*****"
            },
            "expires": null
        }
```