Connections

Every connection should have a way how to check if the used API Key/Token is valid (Validation Endpoint). That means each connection should have a part that uses the used API Key/Token against some endpoint that requires only the API Key/Token to run. For example, User Info endpoint or any endpoint which is used to List data.

The validation endpoint is located:

• OAuth1 and OAuth2 - the info directive

• API Key, Basic Auth, Digest Auth, Other - the url which is in the Communication tab

Right API Key

Right OAuth

Wrong

The API Key is checked against /whoami endpoint which in case of wrong API Key returns an error and the connection won't be created.

Copy

{
    "authorize": {
        ...
    },
    "token": {
        ...
    },
    "info": {
        "url": "https://api.dropboxapi.com/2/users/get_current_account",
        "method": "POST",
        "headers": {
            "authorization": "Bearer {{connection.accessToken}}"
        },
        "body": "{{null}}",
        "response": {
            "uid": "{{body.account_id}}",
            "metadata": {
                "type": "email",
                "value": "{{body.email}}"
            },
            "error": {
                "message": "[{{statusCode}}] {{if(body.error_summary, body.error_summary, body)}}"
            },
            "data": {
                "root_namespace_id": "{{body.root_info.root_namespace_id}}"
            }
        },
        "log": {
            "sanitize": [
                "request.headers.authorization"
            ]
        }
    },
    "invalidate": {
        ...
    }
}

An example of the "info" part of the Dropbox Oauth2 connection.

There is no endpoint to check whether entered credentials like API Key, Username & Password, etc. were correct and will allow the connection to be created with anything, including wrong credentials.

Connection metadata

It is recommended to use the metadata parameter to store the account's name or email. This allows users to easily distinguish their stored connections, especially if they don't name their connections in a good manner.

Occurrence in a module

Code

Notice the value in the brackets after the user's connection name. This value is taken from the metadata parameter.

Copy

...
"response": {
    "metadata": {
            "type": "email", //allowed values are "email" and "text"
            "value": "{{body.data.user.email}}"
        }
},
...

Editable connection

We recommend allowing users to edit their connections after they create them. Updating a connection simplifies scenario and user credential maintenance when there's a change in the user's organization. You can read more about editable connections here.

To allow users to edit a connection:

1. Go to the Parameters tab of the connection.

2. Check that each parameter which original value should be kept secret has the password type.

   The parameters with the password type don't show the original connection's parameter value, while the parameters with the text type show the value used by the current connection.

3. Add the editable: true property for each parameter in the connection.

For example:

[
    {
        "help": "Your MailerLite API Key.",
        "name": "apiKey",
        "type": "password",
        "label": "API Key",
        "editable":true,
        "required": true
    }
]

Error handling

Error handling can be used from the Base tab and follows the same rules.

The only difference is where to use it in what type of connection. For example, in connection types OAuth 1.0 and OAuth 2.0, the error handling should be in the "info" part.