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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://flowmate.gitbook.io/flowmate-documentation/using-the-flowmate-api/authentication-system.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.