REST API Data Sources: Configuration and Authentication

When to Use REST API Sources

Use the REST API data source type when you want to pull data from a web service that is not covered by one of clariBI's built-in integrations (Google Analytics, Jira, etc.). Any service that returns JSON over HTTP can be connected.

Common examples:

Internal company APIs
SaaS platforms with public APIs (e.g., Stripe, Airtable)
Open data feeds (government data, weather APIs)
Custom data warehouses with REST interfaces

Creating a REST API Data Source

Step 1: Open the Wizard

Navigate to Data Sources and click Add Source. Select API as the data source type.

Step 2: Basic Configuration

Field	Description	Example
Display Name	Friendly name	"Stripe Transactions"
Base URL	The API endpoint URL	`https://api.stripe.com/v1/charges`
HTTP Method	GET, POST, or PUT	`GET`
Content Type	`application/json` or `application/x-www-form-urlencoded`	`application/json`

REST API configuration form

Step 3: Authentication

Choose one of the four supported authentication methods:

API Key

Send an API key as a header or query parameter.

Setting	Example
Header Name	`X-API-Key`
API Key Value	`sk_live_abc123...`

Or as a query parameter:

Setting	Example
Parameter Name	`api_key`
Parameter Value	`sk_live_abc123...`

Bearer Token

Sends an Authorization: Bearer <token> header.

Setting	Example
Token	`eyJhbGciOiJIUzI1NiIs...`

This is the most common method for modern APIs.

OAuth 2.0

For services that require OAuth authentication:

Enter the Authorization URL and Token URL
Provide your Client ID and Client Secret
Specify the Scopes required
Click Authorize -- you will be redirected to the service to grant access
On return, clariBI stores the refresh token and handles token renewal automatically

Basic Auth

Sends a base64-encoded username:password in the Authorization header.

Setting	Example
Username	`admin`
Password	`secret123`

Use this for legacy APIs that do not support token-based auth.

Step 4: Request Headers and Parameters

Add any additional headers or query parameters the API requires:

Custom headers -- e.g., Accept: application/json, X-Custom-Header: value
Query parameters -- e.g., limit=100, status=active
Request body (POST only) -- a JSON body sent with POST requests

Step 5: Response Mapping

clariBI needs to know where the data lives in the API response. Configure:

Data Path -- the JSON path to the array of records. For example, if the API returns:

{
  "status": "ok",
  "data": {
    "records": [...]
  }
}

Set the data path to data.records.

Column Mapping -- clariBI auto-detects columns from the first response. You can rename columns, change data types, or exclude fields you do not need.

Step 6: Pagination

If the API paginates results, configure pagination so clariBI fetches all pages:

Pagination Type	How It Works
Offset/Limit	Increments an `offset` parameter by the `limit` value each page
Cursor	Uses a `next_cursor` field from the response to request the next page
Link Header	Follows the `Link` header's `next` URL (standard REST pagination)
Page Number	Increments a `page` parameter starting from 1

Set the maximum pages to prevent runaway fetching. A reasonable default is 100 pages.

Step 7: Test and Save

Click Test Connection. clariBI makes a single API call, shows the response status code, and previews the first few records. Verify the data looks correct, then click Connect.

Sync Scheduling

After the initial connection, configure how often clariBI pulls fresh data:

Manual -- sync only when you click the Sync button
Hourly -- good for real-time dashboards
Daily -- suitable for most reporting needs
Weekly -- for data that changes infrequently
Custom Cron -- specify an exact schedule

Handling API Rate Limits

Many APIs enforce rate limits. clariBI handles this by:

Respecting Retry-After headers when receiving 429 (Too Many Requests) responses
Adding configurable delays between pagination requests (default: 200ms)
Allowing you to set a custom delay in the source settings
Automatically retrying failed requests up to 3 times with exponential backoff

If syncs consistently fail due to rate limits, increase the delay or reduce the sync frequency.

Data Type Overrides

The auto-detected column types are usually correct, but you can override them. Click any column in the mapping interface and change its type (text, number, date, boolean).

Common API Integrations

While clariBI has built-in connectors for popular services, the REST API source lets you connect to any service with an HTTP API. Some common examples:

Service	Auth Type	Notes
Stripe	Bearer Token	Use your secret API key as the token
Airtable	Bearer Token	Use a personal access token
Any REST API	Varies	Use API Key, Bearer Token, OAuth 2.0, or Basic Auth as needed

For services with dedicated clariBI integrations (Google Analytics, Jira, etc.), use the built-in connector instead of the REST API source -- it handles authentication, pagination, and field mapping automatically.

Troubleshooting

401 Unauthorized: Your authentication credentials are incorrect or expired. For Bearer tokens, check if the token has an expiration. For OAuth, try re-authorizing.

403 Forbidden: Your credentials are valid but lack permission for the requested endpoint. Check the API's documentation for required scopes or roles.

404 Not Found: The URL is wrong. Double-check the base URL and any path parameters.

Timeout: The API took too long to respond. Increase the timeout setting in the data source configuration (default is 30 seconds, maximum is 120 seconds).

Empty data: The data path may be incorrect. Use the test response to find the correct JSON path to your records array.