API Authentication
If you need to call an authenticated API, you can create a REST API or GraphQL Integration that will automatically authenticate the endpoint when it is called. Authenticated API Integrations automatically fetch a token if needed and manage the caching of the tokens.
Authentication
Authentication is checked directly before each API execution. When an API is executed in Superblocks, the execution environment first checks to see if non-expired tokens are cached. If not, the tokens are refreshed. Refreshing the tokens may involve any of:
- Silently refreshing the tokens in the background
- Presenting a modal to the user to log in
- Redirecting to an OAuth provider to log in with SSO
The rest of the document outlines the natively supported authentication methods.
Basic Authentication
HTTP Basic Authentication automatically adds a header to your request with the credentials. It is the base64 encoding of the username and password concatenated together with a ":".
Simply enter the username and password on the Integration page and the appropriate Authorization header will be included on requests to this resource.
By default, the same credentials are Shared across all users. This means that all end-users will use these credentials when accessing this API. Deselecting this option will prompt the users for a set of username/password credentials. Superblocks will cache those credentials for that user until they are logged out.
Bearer Token
To authenticate using a Bearer Token, simply choose this option from the list of available authentication methods. In the Token field, enter your API Key value.
Anytime you use this integration, the Token value will be appended to the text Bearer in the required format to the request Authorization header as follows Authorization: Bearer <Your API Key>.
Using the Bearer Token with the On-Premise Agent
Users who use the On-Premise Agent can pull the token from an environment variable using the {{Env}} notation:
API Key
API Key auth lets you send a key-value pair to the API either in the request Header or Query Parameters. To authenticate using an API Key, choose this option from the list of available authentication methods. In the Key field, specify the Header key or Query Parameter that will be used. In the Value field, enter the API Key.
Anytime you use this integration, the relevant information will be appended to your request Headers or the URL query string.
OAuth 2.0
Superblocks natively supports authenticating with many different OAuth 2.0 flows. All of the flows result in a token being retrieved. The OAuth token can be referenced in the Integration form as {{ oauth.token }}. For example, here's how to include it as a Bearer token:
Choosing a Grant Type
The OAuth 2 specification supports many different ways to fetch an OAuth token. Superblocks supports the most common authentication methods. To determine which grant type to use, reference the documentation for the API you're integrating with Superblocks. Searching for the grant_type parameter that is used in their authentication requests will indicate which OAuth grant type should be used.
Grant types can also be referred to as "OAuth flows". This table summarizes the differences between the supported grant types:
| Grant Type / Flow | Headless | Access User Resources | Support Refresh Flow |
|---|---|---|---|
| Client Credentials | Yes | No | No |
| Authentication Code | No | Yes | Yes |
| Implicit | No | Yes | No |
| Password (Legacy) | No | Yes | Yes |
Headless - An authentication method is headless if it doesn't need any input from users (e.g. Logging in with Google or a username/password). Only headless authentication methods can be used in workflows/scheduled jobs.
Access User Resources - Authentication methods that ask users to log in with their own credentials have the ability to query data that is specific to the end-user that is logging in.
Support Refresh Flow - Authentication methods that support the refresh flow can have their token automatically refreshed. When the token is refreshed, a new token is fetched without needing to ask the end-user for their credentials again.
- Client Credentials Grant
- Authentication Code
- Implicit Grant
- Password Grant (Legacy)
OAuth 2.0 - Client Credentials Grant
The Client Credentials flow is commonly used for machine-to-machine authentication. It authenticates the Superblocks app with a client ID and client secret. The tokens are cached on the backend.
A client ID and client secret are required to authenticate the client. They are usually found in an API developer dashboard. It is usually in this dashboard where you can also configure the permitted redirect URIs:
Superblock's redirect URIs must be added to the OAuth provider's allow-list of valid redirect URIs: https://app.superblocks.com/oauth/callback
Audience is the intended recipient of the token, most likely a resource server (e.g. https://api-a.example.com). It's important to note, however, that the specific format and interpretation of the "audience" parameter can vary depending on the OAuth 2.0 server implementation and the requirements of the service or resource provider.
Scopes is a space-separated list of permissions as defined by the API. They usually look like either simple strings (e.g. email) or longer paths (e.g.api.playlists.read).
After authorizing the user (usually via a login page), a token is fetched with the returned code securely either in the Superblocks Cloud or on your On-premise Agent. Tokens are then securely stored in the Superblocks Cloud.
OAuth 2.0 - Authentication Code Grant
The OAuth 2.0 Authentication Code flow allows users to log in with their credentials (e.g. through an SSO provider) and to securely store the token associated with the logged in user without ever exposing the token to the API user. This is the recommended OAuth flow to use.
Users are redirected to a login page, so setting the redirect endpoint in the 3rd party OAuth authorization URL is required.
A client ID and client secret are required to authenticate the client. They are usually found in an API developer dashboard. It is usually in this dashboard where you can also configure the permitted redirect URIs:
Superblock's redirect URIs must be added to the OAuth provider's allow-list of valid redirect URIs: https://app.superblocks.com/oauth/callback
Audience is the intended recipient of the token, most likely a resource server (e.g. https://api-a.example.com). It's important to note, however, that the specific format and interpretation of the "audience" parameter can vary depending on the OAuth 2.0 server implementation and the requirements of the service or resource provider.
Scopes is a space-separated list of permissions as defined by the API. They usually look like either simple strings (e.g. email) or longer paths (e.g.api.playlists.read).
After authorizing the user (usually via a login page), a token is fetched with the returned code securely either in the Superblocks Cloud or on your On-premise Agent. Tokens are then securely stored in the Superblocks Cloud.
In this flow, the tokens are cached in the backend in Superblocks Cloud.
OAuth 2.0 - Implicit Grant
The Implicit OAuth 2.0 flow is very similar to the Authentication Code flow but directly exposes the token to the frontend. It is a flow that redirects to a login page, so setting the redirect endpoint in the 3rd party OAuth provider is required. Automatic token refreshing is not supported in this flow.
The tokens retried by this flow are cached on the frontend, since they have already been exposed to the browser.
A client ID and client secret are required to authenticate the client. They are usually found in an API developer dashboard. It is usually in this dashboard where you can also configure the permitted redirect URIs:
Superblock's redirect URIs must be added to the OAuth provider's allow-list of valid redirect URIs: https://app.superblocks.com/oauth/callback
Audience is the intended recipient of the token, most likely a resource server (e.g. https://api-a.example.com). It's important to note, however, that the specific format and interpretation of the "audience" parameter can vary depending on the OAuth 2.0 server implementation and the requirements of the service or resource provider.
Scopes is a space-separated list of permissions as defined by the API. They usually look like either simple strings (e.g. email) or longer paths (e.g.api.playlists.read).
OAuth 2.0 - Password Grant (Legacy)
The Password OAuth 2.0 flow converts a fixed username and password into a more secure short-lived token that is frequently updated. Superblocks enables you to choose between either specifying a shared username and password for all users, or to prompt users with a username and password when they log in. When configured to fetch username/password credentials directly from the end-user, tokens fetched by this flow are cached on the frontend.
A client ID and client secret are required to authenticate the client. They are usually found in an API developer dashboard. It is usually in this dashboard where you can also configure the permitted redirect URIs:
Superblock's redirect URIs must be added to the OAuth provider's allow-list of valid redirect URIs: https://app.superblocks.com/oauth/callback
Audience is the intended recipient of the token, most likely a resource server (e.g. https://api-a.example.com). It's important to note, however, that the specific format and interpretation of the "audience" parameter can vary depending on the OAuth 2.0 server implementation and the requirements of the service or resource provider.
This type of flow is rarely used. It is mainly used by legacy systems as they migrate to OAuth 2.
Optionally, if your API uses 1 fixed set of credentials, you can use those credentials to authenticate all end-users. If you choose to share credentials with all users, the credentials are cached on the backend.
Redirect Flows
Since authentication is checked right before API execution, and therefore could be triggered while a user is using an app, the flows that require redirection are redirected in a new browser tab. This enables the user to maintain their app state after they log in and API execution can pick up right where it left off.
Superblock's redirect URIs must be added to the OAuth provider's allow-list of valid redirect URIs: https://app.superblocks.com/oauth/callback
Note: some browsers may block frequent redirects/popups if an API uses a lot of separate unauthenticated integrations. The user may be prompted in a modal to open the login modal if several are required to fully authenticate the user.
Firebase
REST APIs can also be authenticated with Firebase. For an in-depth guide to setting up Firebase, see our Firebase Authentication guide. The Firebase authentication token can be specified anywhere in the form, but is commonly referred to when defining an Authorization Bearer header. Firebase access tokens are cached on the frontend.
Note: this is only supported for REST API integrations and not for GraphQL integrations.
Token Caching
Frontend Caching
Some authentication methods are cached on the frontend via cookies. When tokens are cached on the frontend the tokens are stored in HTTP-Only Secure cookies that are not accessible to JavaScript. They are only sent to the Superblocks Cloud (or the On-premise Agent if configured) on App API execution.
Authentication methods that are cached on the front-end are flows that would need to expose the token to the browser in any case (i.e. Firebase and OAuth 2.0's Implicit Flow).
Authentication methods that support frontend token caching tokens:
- Firebase
- OAuth 2.0 Implicit Grant
- OAuth 2.0 Password Grant (dynamically fetching username/passwords)
Backend Caching
Tokens may also be cached in Superblocks Cloud. With this method the tokens are never directly exposed to the end user. The access token will be automatically reused if it is not expired, and refreshed if a valid refresh token is available.
Authentication methods that support backend token caching:
- OAuth 2.0 Authentication Code
- OAuth 2.0 Client Credentials
- OAuth 2.0 Password Grant (shared username/password)
Token Redaction
Fetched API tokens will only be available to developers using a REST API Integration if the token is otherwise accessible from the browser while authenticating.
| Authentication Method | Login Method | Token Redacted | Cache Location |
|---|---|---|---|
| Basic Auth (Shared credentials) | Headless | Yes | None |
| Basic Auth (User credentials) | Login Modal | No | HTTP-Only Cookie |
| OAuth 2.0 - Client Credentials | Headless | Yes | Superblocks Cloud |
| OAuth 2.0 - Authorization Code | Login Modal | Yes | Superblocks Cloud |
| OAuth 2.0 - Implicit | Login Modal | No | HTTP-Only Cookie |
| OAuth 2.0 - Password (Legacy) (Shared Credentials) | Headless | Yes | Superblocks Cloud |
| OAuth 2.0 - Password (Legacy) (User Credentials) | Login Modal | No | HTTP-Only Cookie |
| Firebase | Login Modal | No | HTTP-Only Cookie |
Logging Out
You can log out users from your Superblocks app by calling the logoutIntegrations() function in the UI. This will clear all cached tokens for that user and prompt them to login again.
Cached tokens are also invalidated when a user logs out of Superblocks.
