Skip to main content

Authenticating APIs

If you need to call an authenticated API, you can create a REST API Integration that will automatically authenticate the endpoint for when you it's called. Authenticated REST API Integrations automatically fetch a token if needed and manage the caching of the tokens.

On this page:

  1. REST Integrations
  2. Authentication
  3. OAuth 2.0
  4. Firebase
  5. Token Caching
  6. Token Redaction
  7. Logging Out

REST Integrations

To create a REST Integration, go to the Integrations tab and select REST API.

REST API Integrations can be easily created from the Integrations page and allow you to create a resource for a commonly used API. You can configure a base URL, shared headers, and the API's authentication scheme. This page outlines the authentication methods that are natively supported in Superblocks. Authentication is configured on the Integration form.

REST API Integrations allow you to configure a base URL and standard headers that should be included in every request

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.

Fixed Authorization Bearer Token

In a REST API integration, you can specify 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.

Basic Authentication

HTTP Basic Authentication automatically adds a header to your request with the credentials. It is the base64 encoding 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.

Authenticating an API with end-user Basic Auth credentials

Users will be prompted to enter their credentials when Share username/password across all users is unselected

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 REST API 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 / FlowHeadlessAccess User ResourcesSupport Refresh Flow
Client CredentialsYesNoNo
Authentication CodeNoYesYes
ImplicitNoYesNo
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.

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:

info

Superblock's redirect URLs must be added to the OAuth provider's allow-list of valid redirect URLs: https://app.superblockshq.com/oauth/callback

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 front-end. 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:

info

Superblock's redirect URLs must be added to the OAuth provider's allow-list of valid redirect URLs: https://app.superblockshq.com/oauth/callback

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.

info

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.

info

Redirect URLs must be added to the OAuth provider's allow-list of valid redirect URLs: https://app.superblockshq.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.

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 PopupYesSuperblocks Cloud
OAuth 2.0 - ImplicitLogin PopupNoHTTP-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.