API credentials

Focus: Understand how to access and use API credentials to connect BI tools, custom applications, and SQL clients to your Metric Store cubes. API credentials provide secure access to your cubes through SQL and REST APIs. These credentials enable you to connect external tools, applications, and clients to query your cube data programmatically.

Accessing API credentials

Opening credentials drawer

Click “API Credentials” button in the Metric Store header
Credentials drawer opens showing available APIs
View credentials for SQL API and REST API

Prerequisites

API credentials are available when:

✅ A project is selected
✅ A branch is selected
✅ Server heartbeat status is “RUNNING”
✅ Server has been initialized

Credentials availabilityIf the API Credentials button is disabled or shows no data, ensure the server heartbeat has reached “RUNNING” status. Credentials are generated after the server successfully starts.

SQL API credentials

Overview

SQL API provides PostgreSQL-compatible connection for BI tools and SQL clients:

PostgreSQL protocol - Standard SQL interface
BI tool integration - Connect Tableau, Power BI, Looker, etc.
SQL client support - Use with any PostgreSQL-compatible client
Direct querying - Execute SQL queries against your cubes

Connection components

Connection string

Complete PostgreSQL connection URL
Includes all connection parameters
Ready to use in connection dialogs

Individual credentials:

Host - Server hostname or IP address
Port - Database port number
Database - Database name
Username - Authentication username
Password - Authentication password

Using SQL API credentials

Connect BI tools

Copy connection string or individual credentials
Open BI tool connection dialog
Select PostgreSQL connection type
Enter credentials (host, port, database, username, password)
Test connection and save

Connect SQL clients

Use any PostgreSQL-compatible SQL client:

pgAdmin - PostgreSQL administration tool
DBeaver - Universal database tool
TablePlus - Modern database client
Command line - psql or other CLI tools

Example connection:

psql -h <host> -p <port> -U <username> -d <database>

Example SQL queries

-- Query cube measures and dimensions
SELECT 
  orders.status,
  orders.total_revenue,
  orders.count
FROM orders
WHERE orders.created_at >= '2024-01-01'
GROUP BY orders.status
ORDER BY orders.total_revenue DESC;

-- Time-based analysis
SELECT 
  orders.created_at,
  orders.total_revenue
FROM orders
WHERE orders.created_at >= '2024-01-01'
  AND orders.created_at < '2024-02-01'
GROUP BY orders.created_at
ORDER BY orders.created_at;

REST API credentials

Overview

REST API provides RESTful access for application integration:

HTTP-based - Standard REST interface
JSON requests/responses - Easy integration
Token authentication - Secure API access
Flexible querying - Build queries programmatically

Connection components

Base URL

API endpoint base URL
Used as prefix for all API requests
Example: https://api.example.com/v1

Authentication token

Bearer token for API authentication
Include in request headers
Keep secure and rotate periodically

Using REST API credentials

API request format

curl -X POST 'https://your-api-url/v1/load' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "measures": ["orders.total_revenue"],
      "dimensions": ["orders.status"],
      "timeDimensions": [{
        "dimension": "orders.created_at",
        "granularity": "day",
        "dateRange": ["2024-01-01", "2024-01-31"]
      }]
    }
  }'

Example queries

Simple query:

{
  "query": {
    "measures": ["orders.total_revenue"],
    "dimensions": ["orders.status"]
  }
}

Time-based query:

{
  "query": {
    "measures": ["orders.total_revenue"],
    "timeDimensions": [{
      "dimension": "orders.created_at",
      "granularity": "month"
    }]
  }
}

Filtered query:

{
  "query": {
    "measures": ["orders.total_revenue"],
    "dimensions": ["orders.status"],
    "filters": [{
      "dimension": "orders.status",
      "operator": "equals",
      "values": ["completed"]
    }]
  }
}

Integration examples

Python:

import requests

url = "https://your-api-url/v1/load"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "query": {
        "measures": ["orders.total_revenue"],
        "dimensions": ["orders.status"]
    }
}

response = requests.post(url, json=data, headers=headers)
results = response.json()

JavaScript:

const url = 'https://your-api-url/v1/load';
const headers = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Content-Type': 'application/json'
};
const data = {
  query: {
    measures: ['orders.total_revenue'],
    dimensions: ['orders.status']
  }
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(results => console.log(results));

Server status

Status indicator

The credentials drawer shows server status:

🟢 Green - Server is running and operational
🔴 Red - Server is stopped or unavailable
🟡 Yellow - Server is starting up (PENDING)

Server restart

If schema changes occur, you may need to restart the API server:

Click “Restart” button in credentials drawer
Wait for restart - Server will restart and reload schema
Status updates - Green indicator when ready
Credentials refresh - May need to refresh credentials after restart

When to restartRestart the API server when:

Schema files are updated and deployed
Cube definitions are modified
Connection issues occur
Server status shows errors

Security best practices

Credential management

Keep secure

Protect credentialsNever share API credentials publicly. Store them securely and use environment variables or secret management tools.

Rotate regularly

Periodic rotationRotate API credentials periodically to maintain security. Update connected applications when credentials change.

Access control

Limit accessOnly share credentials with authorized users and applications. Use role-based access control where possible.

Monitor usage

Track accessMonitor API usage and access patterns to detect unusual activity or potential security issues.

Connection security

Use HTTPS - Always use encrypted connections
Token expiration - Configure token expiration policies
IP whitelisting - Restrict access to known IP addresses
Rate limiting - Implement rate limits to prevent abuse
Audit logging - Track API access and usage

Troubleshooting

Common issues

Credentials not showing

Possible causes:

Server heartbeat not RUNNING
Project or branch not selected
Server not initialized

Solutions:

Wait for heartbeat to reach RUNNING status
Verify project and branch are selected
Check server status indicator
Try refreshing the page

Connection failures

Possible causes:

Incorrect credentials
Network connectivity issues
Server not running
Firewall blocking connections

Solutions:

Verify credentials are correct (copy again)
Check network connection
Verify server status is RUNNING
Check firewall and security group settings
Test connection from different network

Authentication errors

Possible causes:

Invalid or expired token
Incorrect authorization header
Token format issues

Solutions:

Verify token is correct and not expired
Check authorization header format: Bearer YOUR_TOKEN
Refresh credentials if token appears invalid
Contact support if issues persist

Debugging connections

Test SQL connection:

# Test PostgreSQL connection
psql -h <host> -p <port> -U <username> -d <database>

# Or test with connection string
psql "postgresql://username:password@host:port/database"

Test REST API:

# Test API endpoint
curl -X POST 'https://your-api-url/v1/load' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"query": {"measures": ["orders.count"]}}'

BI Integration

Sync BI toolsLearn how to set up automatic synchronization with BI tools.

Cube Playground

Build queriesUse Cube Playground to build and test queries before connecting external tools.

Get Started

Core Features

Accessing API credentials

Opening credentials drawer

Prerequisites

SQL API credentials

Overview

Connection components

Using SQL API credentials

Connect BI tools

Connect SQL clients

Example SQL queries

REST API credentials

Overview

Connection components

Using REST API credentials

API request format

Example queries

Integration examples

Server status

Status indicator

Server restart

Security best practices

Credential management

Keep secure

Rotate regularly

Access control

Monitor usage

Connection security

Troubleshooting

Common issues

Debugging connections

BI Integration

Cube Playground

Get Started

Core Features

​Accessing API credentials

​Opening credentials drawer

​Prerequisites

​SQL API credentials

​Overview

​Connection components

​Using SQL API credentials

​Connect BI tools

​Connect SQL clients

​Example SQL queries

​REST API credentials

​Overview

​Connection components

​Using REST API credentials

​API request format

​Example queries

​Integration examples

​Server status

​Status indicator

​Server restart

​Security best practices

​Credential management

Keep secure

Rotate regularly

Access control

Monitor usage

​Connection security

​Troubleshooting

​Common issues

​Debugging connections

BI Integration

Cube Playground

Accessing API credentials

Opening credentials drawer

Prerequisites

SQL API credentials

Overview

Connection components

Using SQL API credentials

Connect BI tools

Connect SQL clients

Example SQL queries

REST API credentials

Overview

Connection components

Using REST API credentials

API request format

Example queries

Integration examples

Server status

Status indicator

Server restart

Security best practices

Credential management

Connection security

Troubleshooting

Common issues

Debugging connections