Documentation

Secrets

Secrets provide an intuitive way to store your security tokens. Using secrets allows you to manage credentials in a single place and prevents leaking credentials by sharing flows.

Multiple secret types exist for different use cases. This page gives an overview of each of them.

Password

Use this type to store a static password, which might be a simple API token.

You can use passwords in scripts (via the script block or in mappings) using the code below:

await secrets.getPassword('SECRET_NAME')

This method returns the plaintext password as a string. Replace SECRET_NAME with the name of the actual secret.

The HTTP request block also accepts this kind of secret. Connecting a password secret to its secret input results in the following HTTP header:

Authorization: Bearer PLAINTEXT_PASSWORD

Providing static API tokens in this format is a common practice. However, some APIs expect a different form, for example, an HTTP header with the name X-API-KEY where the password is its plain value. You can use getPassword method described above in this case. You can drag the pin right to the code field to the headers input pin in the mapping dialog for the HTTP request block. You will be able to specify a header name when you do this.

Basic auth

This type can provide basic authorization for HTTP request blocks or require authorization for HTTP endpoint flows.

Providing this secret to an HTTP request block will result in the following HTTP header:

Authorization: Basic BASE64(USERNAME:PASSWORD)

To require basic authentication for HTTP endpoints, go to the HTTP endpoint flow's start block configuration. Uncheck "open access" and then check a secret of this type.

HTTP headers

Some services require multiple HTTP headers or use a custom name or scheme. The HTTP headers secret allows you to set various custom headers with static values.

OAuth2

Many popular web services require OAuth2 authorization. This type of authorization is used to give an application (partial) access to your account on that platform so that the application can perform actions on your behalf. In this case, the application is your Flowlet workspace.

Flowlet implements the Authorization Code Grant as described in RFC6749 with the PKCE extension (RFC7636). Upon successful authorization, the application receives an access token and an optional refresh token. Flowlet uses the refresh token to obtain a new access token once it expires.

Like password and basic auth, OAuth2 secrets can be provided to the HTTP request block to authenticate outgoing API requests. That adds the following HTTP header:

Authorization: Bearer ACCESS_TOKEN

Configuring OAuth2 involves the exchange of some details from both the application (your Flowlet workspace) and the identity provider (IdP). The general process is outlined below, but the process at the IdP might slightly differ.

  1. Register your application at the IdP (like your CRM or Twitter, for example). You most likely have to do this in a "Your apps" section at the account configuration or in a separate developer portal.
  2. In Flowlet, click on Add secret and choose a name. You will see that the Redirect URI updates to reflect this name. You need to provide this URL at the IdP. Most IdPs will ask for this when registering your app.
  3. The IdP will give you a Client ID and Client secret after registering your app. Copy over these values to the Flowlet secret.
  4. You need to provide the authorization endpoint and token endpoint of the IdP. Some IdPs give this information in the process above, but often you need to look this up in their developer documentation. A few examples are listed below.
  5. Provide the scope for your application. The scope is a space-separated string of permissions you want your app to have. You should look up the IdP's documentation for the available scopes list and which to add. When connecting to an OpenID provider, you may use the OpenID standard claims "openid profile email" as a starting point.
  6. Scan the list of scopes for a "refresh" permission. Many APIs require a particular scope to provide a refresh token. The authorization will work without but cannot be refreshed when the access token expires.
  7. Save the secret in Flowlet and click on the "Manage tokens" link. A dialog opens that shows the stored access and refresh token, if any. These are now absent since we've not authorized our app yet. Click on the "Request access token" link to do that. If all details are correct, this will take you to the IdP, where you can allow access.
  8. You will return to the secrets page after granting access. Click on the "Manage tokens" link again to check if you have an access and refresh token. The refresh token might be missing due to a missing scope, or because the IdP did not support refresh tokens.

Examples of the Authorize URIs are:

https://api.twitter.com/2/oauth2/authorize
https://slack.com/oauth/v2/authorize
https://discord.com/oauth2/authorize

Token endpoints for these APIs are:

https://api.twitter.com/2/oauth2/token
https://slack.com/api/oauth.v2.access
https://discord.com/api/oauth2/token

An example of integration using this secret type is found in the blogpost on Slack commands.

The refresh token is used only when performing an HTTP request with this secret while the access token is expired. As a result, the "Manage tokens" dialog might show that the access token is expired. That does not necessarily mean that you lost access unless the refresh token is missing.

HS256 Secret and RS256 Key Pair

You can use these secrets to sign data Json Web Tokens (JWT) or JSON Web Signature (JWS). JWTs are commonly used for handling authorization.

HS256 uses a shared secret, while RS256 uses asymmetric keys (public and private keys) to generate and verify signatures.

Authorize requests

Flowlet supports authorization with Json Web Tokens in two ways:

  1. You can use these secrets in code with the Jose.signJws and Jose.verifyJws methods.
  2. Use the secret in HTTP endpoint flows to configure access.

The latter also checks if the JWT has the required scope.

Encrypting data

The RS256 Key Pair allows you to encrypt and decrypt data using the Jose.encryptJwe and Jose.decryptJwe methods.

MySQL and PostgreSQL

These secret types allow you to provide credentials for external databases. You can use it with the SQL block or in code using the SQL function.