API Guide

API Referencev2.0

Master the API with our comprehensive guide covering authentication, service account management, and data querying. Includes production-ready code samples in multiple programming languages.

ReactPythonJavaScriptGoC++

Quick start

This guide covers two main authentication flows:

1. User Authentication - JWT-based login for identity management
2. Service Account Authentication - Token-based access for data operations

---

🚀 Base URL and configuration

Base URL:https://www.example.com

All endpoints below are relative to this base URL.

---

🔐 Authentication overview

1

User Login (JWT)

Authenticate with email/password to get JWT token

→

2

Service Account

Create or manage service account tokens

→

3

Data Access

Use service token to access data APIs

Authentication methods

Method	Header	Usage
User Login	Authorization: Bearer <JWT>	Identity management endpoints
Service Account	x-auth-token: <token>	Data access endpoints

---

🔑 User authentication

Login endpoint

POST/idp/api/v1/user/login

Request Body

{
  "email": "<your-email>",
  "password": "<your-password>"
}

Response

✅ Success: Returns Authorization: Bearer <JWT> header

📝 Note: Extract only the token value (remove "Bearer " prefix)

JWT usage

Use the JWT token for all IdP (Identity Provider) endpoints including:

• Creating service accounts
• Resetting tokens
• Deleting service accounts

---

🏢 Identity (IdP) APIs

Authentication Required

All IdP endpoints require the JWT token from login: Authorization: Bearer <JWT>

Create Service Account

POST/idp/api/v1/company/serviceAccount

Request Body

{
  "name": "<service-account-name>",
  "description": "<optional-description>"
}

Response Example

{
  "token": "<service-account-token>",
  "expiryInSeconds": 31536000
}

💾 Save this token! You'll use it as x-auth-token for data APIs.

Reset Service Account Token

GET/idp/api/v1/company/serviceAccount/:id/token/reset

Query Parameters

• neverExpires (optional): Set to true for non-expiring tokens

Response Examples

With Expiry

{
  "token": "<new-token>",
  "expiryInSeconds": 31536000,
  "expiryDate": "2026-08-05T15:19:01.851+0000"
}

Non-Expiring

{
  "token": "<new-token>",
  "neverExpires": true
}

Delete Service Account

DELETE/idp/api/v1/company/serviceAccount/:id

Response: 200 OK with empty body on success

---

📊 Data (noCo) APIs

Authentication Required

All noCo endpoints require the service account token: x-auth-token: <service-account-token>

Get Table Schema

GET/noCo/api/v2/workspaces/:workspaceId/tables/:tableId

Returns table metadata including columns and their properties. Use this to discover valid column names for queries.

Get Table Data

POST/noCo/api/v2/workspaces/:workspaceId/tables/:tableId/data/external

Request Body Examples

Minimal Paging

{
  "requestPageDetails": {
    "pageNumber": 1,
    "pageSize": 101
  }
}

With Filter and Sort

{
  "requestPageDetails": { 
    "pageNumber": 1, 
    "pageSize": 101 
  },
  "whereClause": "name = 'krishna'",
  "sortOptions": [
    { "columnName": "name", "direction": "ASC" },
    { "columnName": "notes", "direction": "DESC" }
  ]
}

⚠️ Important: Column names in whereClause and sortOptions must exist. Fetch them via Get Table Schema first.

Execute SQL Query

POST/noCo/api/v2/workspaces/:workspaceId/tables/:tableId/executeQuery

Request Body

{ 
  "value": "SELECT * FROM table_<suffix>" 
}

Response

May return JSON with columns and export fileName (CSV), or empty body with 200 OK depending on query and server configuration.

---

🔄 Complete workflow

🔐

Step 1: Login

POST /idp/api/v1/user/login → Extract JWT from Authorization header

🔑

Step 2: Create Service Account

Use JWT to create or reset a service account token

📊

Step 3: Access Data

Use service account token as x-auth-token for noCo endpoints

---

📋 Common headers

Endpoint Type	Required Headers	Example
All Requests	Content-Type: application/json	Content-Type: application/json
IdP Endpoints	Authorization: Bearer <JWT>	Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
noCo Endpoints	x-auth-token: <service-token>	x-auth-token: sa_1234567890abcdef...

---

⚠️ Security and error handling

🔒 Token Security

• Treat all tokens as secrets - never commit to source control
• Prefer tokens with expiry over non-expiring tokens
• Rotate tokens regularly for enhanced security

🔄 Error Handling

• Handle HTTP 401/403 by refreshing JWT or resetting service account token
• Use HTTPS only (all endpoints are https://)
• Implement proper error logging and monitoring

---

💻 Code samples

Before Running

Replace placeholders like YOUR_JWT, YOUR_SERVICE_TOKEN, YOUR_WORKSPACE_ID, and YOUR_TABLE_ID with your actual values.

React

import React, { useEffect, useState } from "react";

export default function QueryTable() {
  const [rows, setRows] = useState([]);
  const [loading, setLoading] = useState(false);
  const token = process.env.REACT_APP_SERVICE_TOKEN;
  const workspaceId = "YOUR_WORKSPACE_ID";
  const tableId = "YOUR_TABLE_ID";

  useEffect(() => {
    async function run() {
      setLoading(true);
      try {
        const res = await fetch(
          `https://www.example.com/noCo/api/v2/workspaces/${workspaceId}/tables/${tableId}/executeQuery`,
          {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              "x-auth-token": token,
            },
            body: JSON.stringify({ value: "SELECT * FROM table_6ec53cc4" }),
          }
        );
        const data = await res.json().catch(() => ({}));
        setRows(data.rows || []);
      } catch (e) {
        console.error(e);
      } finally {
        setLoading(false);
      }
    }
    run();
  }, [token, workspaceId, tableId]);

  if (loading) return <div>Loading…</div>;
  return (
    <table>
      <tbody>
        {rows.map((r, i) => (
          <tr key={i}>
            {Object.values(r).map((v, j) => (
              <td key={j}>{String(v)}</td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

Python

import os
import requests

BASE = "https://www.example.com"

# 1) Login (JWT)
login = requests.post(
    f"{BASE}/idp/api/v1/user/login",
    json={"email": os.environ["EMAIL"], "password": os.environ["PASSWORD"]},
)
jwt = login.headers.get("Authorization", "").replace("Bearer ", "")

# 2) Create service account token
svc = requests.post(
    f"{BASE}/idp/api/v1/company/serviceAccount",
    headers={"Authorization": f"Bearer {jwt}"},
    json={"name": "sales", "description": ""},
)
service_token = svc.json()["token"]

# 3) Execute a query with service token
workspace_id = "YOUR_WORKSPACE_ID"
table_id = "YOUR_TABLE_ID"
q = requests.post(
    f"{BASE}/noCo/api/v2/workspaces/{workspace_id}/tables/{table_id}/executeQuery",
    headers={"x-auth-token": service_token, "Content-Type": "application/json"},
    json={"value": "SELECT * FROM table_6ec53cc4"},
)
print(q.json())

JavaScript

const BASE = "https://www.example.com";

async function login(email, password) {
  const res = await fetch(`${BASE}/idp/api/v1/user/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password }),
  });
  const auth = res.headers.get("Authorization") || "";
  return auth.replace("Bearer ", "");
}

async function createServiceToken(jwt) {
  const res = await fetch(`${BASE}/idp/api/v1/company/serviceAccount`, {
    method: "POST",
    headers: { Authorization: `Bearer ${jwt}`, "Content-Type": "application/json" },
    body: JSON.stringify({ name: "sales", description: "" }),
  });
  const body = await res.json();
  return body.token;
}

async function executeQuery(serviceToken, workspaceId, tableId, sql) {
  const res = await fetch(
    `${BASE}/noCo/api/v2/workspaces/${workspaceId}/tables/${tableId}/executeQuery`,
    {
      method: "POST",
      headers: { "x-auth-token": serviceToken, "Content-Type": "application/json" },
      body: JSON.stringify({ value: sql }),
    }
  );
  return res.json();
}

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "strings"
)

type TokenResp struct { Token string `json:"token"` }

func main() {
  base := "https://www.example.com"

  loginBody := []byte(`{"email":"YOUR_EMAIL","password":"YOUR_PASSWORD"}`)
  req, _ := http.NewRequest("POST", base+"/idp/api/v1/user/login", bytes.NewBuffer(loginBody))
  req.Header.Set("Content-Type", "application/json")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  jwt := strings.TrimPrefix(resp.Header.Get("Authorization"), "Bearer ")

  body := []byte(`{"name":"sales","description":""}`)
  req2, _ := http.NewRequest("POST", base+"/idp/api/v1/company/serviceAccount", bytes.NewBuffer(body))
  req2.Header.Set("Authorization", "Bearer "+jwt)
  req2.Header.Set("Content-Type", "application/json")
  resp2, _ := http.DefaultClient.Do(req2)
  defer resp2.Body.Close()
  var tr TokenResp
  json.NewDecoder(resp2.Body).Decode(&tr)

  workspaceId := "YOUR_WORKSPACE_ID"
  tableId := "YOUR_TABLE_ID"
  payload := map[string]string{"value": "SELECT * FROM table_6ec53cc4"}
  buf, _ := json.Marshal(payload)
  req3, _ := http.NewRequest("POST", fmt.Sprintf("%s/noCo/api/v2/workspaces/%s/tables/%s/executeQuery", base, workspaceId, tableId), bytes.NewBuffer(buf))
  req3.Header.Set("x-auth-token", tr.Token)
  req3.Header.Set("Content-Type", "application/json")
  resp3, _ := http.DefaultClient.Do(req3)
  defer resp3.Body.Close()
  out, _ := io.ReadAll(resp3.Body)
  fmt.Println(string(out))
}

C++

#include <curl/curl.h>
#include <iostream>
#include <string>

static size_t WriteCB(void* contents, size_t size, size_t nmemb, void* userp) {
  ((std::string*)userp)->append((char*)contents, size*nmemb);
  return size*nmemb;
}

int main() {
  const std::string BASE = "https://www.example.com";
  const std::string SERVICE_TOKEN = "YOUR_SERVICE_TOKEN";
  const std::string WORKSPACE = "YOUR_WORKSPACE_ID";
  const std::string TABLE = "YOUR_TABLE_ID";

  CURL* curl = curl_easy_init();
  if(!curl) return 1;

  std::string url = BASE + "/noCo/api/v2/workspaces/" + WORKSPACE + "/tables/" + TABLE + "/executeQuery";
  std::string payload = "{"value":"SELECT * FROM table_6ec53cc4"}";
  struct curl_slist* headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: application/json");
  headers = curl_slist_append(headers, ("x-auth-token: " + SERVICE_TOKEN).c_str());

  curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload.c_str());

  std::string response;
  curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCB);
  curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);

  CURLcode res = curl_easy_perform(curl);
  if(res != CURLE_OK) std::cerr << "curl error: " << curl_easy_strerror(res) << "\n";
  std::cout << response << std::endl;

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);
  return 0;
}

---