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.

Fixed Authorization Bearer Token

Fixed Authorization bearer tokens can be specified as a header that will be included in every request that uses this resource. To specify a fixed Authorization header, simply add it to the list of headers in the Integration form. When using this integration, the header will automatically be included.

Use a fixed authorization bearer token when authenticating an API

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

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.

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