Skip to main content

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

Use basic authentication when authenticating an API

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.

Deselect 'shared across all users' to prompt them for username and password

A prompt to the user to log in with their username and password for basic authentication

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

Use a fixed authorization bearer token when authenticating an API

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:

Users who use the On-premise Agent can pull the token from environment variables


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.

API key authentication for REST and GraphQL APIs

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:

Include an oauth token dynamically 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 / FlowHeadlessAccess User ResourcesSupport Refresh Flow
Client CredentialsYesNoNo
Authentication CodeNoYesYes
Password (Legacy)NoYesYes

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.

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:

Audience is the intended recipient of the token, most likely a resource server (e.g. 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 (

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.

Use client credentials grant to authenticate an API

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.


Redirect URIs must be added to the OAuth provider's allow-list of valid redirect URIs:

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.


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.

Reference the firebase token with {{firebase.token}}

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 MethodLogin MethodToken RedactedCache Location
Basic Auth (Shared credentials)HeadlessYesNone
Basic Auth (User credentials)Login ModalNoHTTP-Only Cookie
OAuth 2.0 - Client CredentialsHeadlessYesSuperblocks Cloud
OAuth 2.0 - Authorization CodeLogin ModalYesSuperblocks Cloud
OAuth 2.0 - ImplicitLogin ModalNoHTTP-Only Cookie
OAuth 2.0 - Password (Legacy) (Shared Credentials)HeadlessYesSuperblocks Cloud
OAuth 2.0 - Password (Legacy) (User Credentials)Login ModalNoHTTP-Only Cookie
FirebaseLogin ModalNoHTTP-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.

Use logoutIntegrations() in order to clear cached tokens for a user and prompt them to login again when using an API