Skip to content
excalibase
getting-started
Connectstable

Connect to your project

Every project on Excalibase Cloud is reached through one public host. The pages in these docs show the cloud address first; running the open-source stack yourself is covered in each page's Self-hosting section.

Base URLhttps://api.excalibase.io
Project idproj-xxxxxxxxxx, shown in Studio on the project's page
Publishable keyesk_pub_..., created in Studio under API keys
ServiceAddress
GraphQL (and realtime over WebSocket)https://api.excalibase.io/{projectId}/graphql
RESThttps://api.excalibase.io/{projectId}/api/v1/{table}
Token exchangehttps://api.excalibase.io/auth/{projectId}/{projectId}/token
Edge functionshttps://api.excalibase.io/functions/v1/{projectId}/{id}

Every example in these docs runs as written against a public demo project (a feedback board, a live poll, a kanban and a link shortener). Its id and publishable key are public on purpose: a publishable key only reaches what the project's API permissions allow its anon role, which is why it is safe in a web page or an app bundle. Swap in your own project id and key to run the same calls against your project.

1. Set the variables

BASE=https://api.excalibase.io
PROJECT_ID=proj-jfp7kx46kb
KEY=esk_pub_live_Tb2pe6iauenJiWtTdBDMbeMp

2. Exchange the key for a token

TOKEN=$(curl -s -X POST "$BASE/auth/$PROJECT_ID/$PROJECT_ID/token" \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"api_key\",\"api_key\":\"$KEY\"}" | jq -r .accessToken)

The answer carries accessToken, refreshToken and expiresIn (seconds). The token is a JWT for the project's anon role. The path has two segments after /auth/: an organization label, which auth ignores, and the project id. Studio, the SDK and these docs write the project id twice.

An end user who signs in with email and password gets a token for their own role in the same way (grant_type password, see Auth).

3. Send the token on every request

curl -s "$BASE/$PROJECT_ID/api/v1/feedback_posts?limit=2" \
  -H "Authorization: Bearer $TOKEN"
curl -s -X POST "$BASE/$PROJECT_ID/graphql" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ publicFeedbackPosts(limit: 2) { id kind body } }"}'

A request with no token at all is not rejected: it runs as the anon role, so a table is readable without a key exactly when anon has been given a permission on it. The token matters when the caller is someone other than anon, and so that the platform can tell which key a call came from. A table or column the role has no permission for answers as if it did not exist.

4. The SDK

@excalibase/sdk does the exchange, refreshes the token before it expires and builds every path above from the base URL and the project id.

npm install @excalibase/sdk graphql-request
import { createClient } from '@excalibase/sdk'

// A publishable key (esk_pub_...) is safe in pages and browser bundles: it only
// reaches what your API permissions allow. There is no process.env in a browser.
const PUBLISHABLE_KEY = 'esk_pub_live_Tb2pe6iauenJiWtTdBDMbeMp'

const db = createClient({
  url: 'https://api.excalibase.io',
  projectId: 'proj-jfp7kx46kb',
  key: PUBLISHABLE_KEY,
})

await db.auth.signInWithApiKey()
console.log(await db.graphql.query('{ publicFeedbackPosts(limit: 2) { id kind } }'))
console.log(await db.rest.get('/feedback_posts?limit=2'))

A script that finishes exits on its own; the refresh timer never holds Node open (SDK 0.11.1 and later). From a browser, the page's origin must be on the project's CORS allowlist in Studio.

Errors

A refused request answers a status, a stable code and a message; see Errors for every code.

Self-hosting

Running the stack yourself changes the host and how you sign in, not the shape of the API: the GraphQL and REST pages each have a Self-hosting section with the local ports and the routes a standalone engine adds. See the Kubernetes runbook for installing the platform.