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 URL | https://api.excalibase.io |
| Project id | proj-xxxxxxxxxx, shown in Studio on the project's page |
| Publishable key | esk_pub_..., created in Studio under API keys |
| Service | Address |
|---|---|
| GraphQL (and realtime over WebSocket) | https://api.excalibase.io/{projectId}/graphql |
| REST | https://api.excalibase.io/{projectId}/api/v1/{table} |
| Token exchange | https://api.excalibase.io/auth/{projectId}/{projectId}/token |
| Edge functions | https://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.