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

There are APIs, which don't have a validation endpoint. In this case, it is recommended to call an endpoint, which will work in every case, and if possible will return the account's data, e. g. an endpoint /about or /me, etc.

Right API Key

Coda (beta) connection example

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.

Right OAuth

{
    "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.

Wrong

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.

Occurence in a module

Example of Connection's Name

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

Code

...
"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
    }
]

Exception: If the service provides each user with a unique URL or domain, the corresponding URL or domain parameter must be non-editable to prevent any potential credential leaks.

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.

Error handling