Skip to main content

Authentication Setup

The Authentication.mdx file serves as a clear, human-readable guide for defining authentication methods and required environment variables when integrating third-party services with Boltic. It outlines how access tokens function, which permissions are necessary, and how to configure credentials to securely connect external platforms.

This document is essential for developers implementing authentication workflows as part of their integration logic. In this file, you as a developer are expected to describe the reader through the complete setup for each integration, including what credentials are needed, where to obtain them, and how to configure them within the Boltic dashboard.

The purpose of this document is to ensure that the integration guide clearly communicates what the tool, integration, or API does, and why it is useful. It should explain the user through the setup and implementation process in a step-by-step manner that is easy to follow.

When an integration (trigger ot activity) requires authentication and you initialize the process to add a new account, the corresponding Authentication.mdx will appear on the authentication page, making it easy for users to find and follow the authentication steps.

Style and Writing Guidelines​

  • Write in .mdx format (Markdown + JSX).
  • Keep sentences short and direct.
  • Use clear, professional English.
  • Use standard Markdown syntax for headings, lists, bold text, and code blocks.
  • Include links to external tools like Google Cloud Console or service-specific portals.
  • Use HTML tags like <a> when you need custom-styled or external links and always include target="_blank" and rel="noopener".
  • Use bold for interface labels or steps (Click **Create**, **API Key**).
  • Avoid technical terms unless it’s part of the API.
  • Use bold for UI elements, such as Save, Cancel, or Add.

Content Structure​

The Authentication.mdx file must follow this structure:

# Integration Name
    * Top-level heading with the name of the integration or node (e.g., **`# Google Programmable Search Engine`**).
    * It should not contain special characters and underscores in the name of an integration.

## Overview
- Briefly describe what the integration does and its primary use case.
- Focus on purpose and benefits, not technical steps.
- Limit to 2–3 short sentences.

## Authentication Ways
- List supported authentication methods (e.g., API Key, OAuth, Access Token).
- Use bullet points for clarity.

## Authentication Method Name
- Provide a dedicated subheading for each authentication method.
- Describe what credentials are needed and how the flow works.
- Include **numbered steps** for setup.
- Emphasize any required configuration in the Boltic dashboard.

## External Links
- Use Markdown (`[text](url)`) or HTML (`<a>`) for links.
- If using HTML, always include:
  - `target="_blank"`
  - `rel="noopener"`

Quality Checklist Before Submission​

Before submitting your authentication documentation, ensure:

  • The document starts with the integration name
  • It includes an overview section
  • All steps are numbered and clear
  • External links are clickable and open in a new tab
  • Formatting is clean, consistent, and follows MDX syntax
  • You avoid placeholder text like YOUR_API_KEY_HERE unless required

Example​

# Google Programmable Search Engine

## Overview

Google Programmable Search Engine (formerly Custom Search Engine) allows you to build a tailored search experience powered by Google's search technology. You can access search results programmatically using the Custom Search JSON API.

## Authentication Ways

- API Key + Search Engine ID

## API Key + Search Engine ID

To authenticate with Google Programmable Search Engine, you need to create a search engine and enable the Custom Search API in Google Cloud to obtain both an API Key and a Search Engine ID.

## Steps

1. **Create a Programmable Search Engine**
    - Go to <a href="https://programmablesearchengine.google.com/" target="_blank" rel="noopener"><span>Programmable Search Engine</span></a>
    - Click **"Create a search engine"**
    - Under **Sites to search**, you can use `www.example.com`, or `*.com` to search the entire web
    - Click **Create**
    - After creation, go to **Control Panel**:
        - Enable **"Search the entire web"** under **Sites to Search**

2. **Get Your Search Engine ID (cx)**
    - In the Control Panel, go to **Basics**
    - Copy the **Search engine ID** — this is your `cx`

3. **Enable the Custom Search API in Google Cloud**
    - Go to <a href="https://console.cloud.google.com/" target="_blank" rel="noopener"><span>Google Cloud Console</span></a>
    - Create a new project (or select an existing one)
    - Navigate to **APIs & Services > Library**
    - Search for **Custom Search API** and click **Enable**

4. **Generate Your API Key**
    - In the same project, go to **APIs & Services > Credentials**
    - Click **Create Credentials > API key**

For more details, see the <a href="https://developers.google.com/custom-search/v1/overview" target="_blank" rel="noopener"><span>Custom Search JSON API documentation</span></a>