Your first API call

Overview

Making your first API call to Oblax involves authenticating with a JWT and performing a CRUD operation. The platform uses two JWT types: Platform JWT for CLI operations and Application JWT for your app’s API calls.

There are three methods to make API calls: CLI (automatically authenticated), SDK (JavaScript/TypeScript), and REST (direct HTTP requests).

Installation

API calls require the Oblax CLI installed and authenticated, or the SDK installed in your project.

CLI Installation

brew tap oblax/tap
brew install obx
obx login

SDK Installation

npm install @oblax/core @oblax/platform-browser @oblax/forms

Configuration

Authentication: Understand Your JWTs

Before making API calls, understand the two token types Oblax uses. You already created your account and were assigned the PLATFORM_USER role.

Platform JWT (for CLI operations)

{
  "iss": "platform.oblax.io",
  "sub": "u:ct2d85u3lg52hbcdkg30",
  "aud": "platform.oblax.io",
  "exp": 2524608000,
  "iat": 1596240000,
  "nbf": 0,
  "full_name": "Your Name",
  "pid": "cnoqeve3lg56dnbek55g",
  "realm": "platform",
  "role": "user"
}

Application JWT (for your app’s API calls)

{
  "iss": "your-app.api.oblax.io",
  "sub": "u:ct2d85u3lg52hbcdkg30",
  "aud": "your-app.api.oblax.io",
  "exp": 2524608000,
  "iat": 1596240000,
  "nbf": 0,
  "full_name": "Your Name",
  "email": "you@example.com",
  "pid": "cnoqeve3lg56dnbek55g",
  "realm": "app:webapp",
  "role": "admin"
}

Key claim reference:

Claim	What It Means
`iss`	Token issuer — your app domain or the platform
`sub`	Subject — your user ID (`u:<hash>` for users, `s:<hash>` for services)
`aud`	Audience — where this token is accepted
`realm`	Access scope — `platform` or `app:<subrealm>`
`role`	Your role within the realm
`pid`	Associated project ID

Method 1: Your First API Call via CLI

The Oblax CLI uses your authenticated session automatically. After obx login, all commands carry your JWT.

List Forms (GET Equivalent)

obx app forms list

Output: Table of all forms in your project.

Get a Single Form (GET by ID)

obx app forms get <form-id>

Example:

obx app forms get f2837hfd17q3phc3

Output: Form details in reverse-table format.

Create a Form (via push workflow)

obx app forms push --data @form.json

This pushes form data to the platform API and returns the created record.

Update a Form

obx app forms push f2837hfd17q3phc3

Pushes updated data for the record with ID f2837hfd17q3phc3.

Pull a Form from Platform

obx app forms pull f2837hfd17q3phc3

Pulls the latest data from the platform for the given record ID.

Delete a Form

obx app forms delete f2837hfd17q3phc3

Deletes the record from the platform and removes the local file.

Method 2: Your First API Call via SDK (JavaScript/TypeScript)

If you’re building a web or mobile front-end, use the Oblax JavaScript SDK.

Installation

npm install @oblax/core @oblax/platform-browser @oblax/forms

Basic Setup

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { forms } from "@oblax/forms";

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [forms()],
});

await oblax.setToken("<your-jwt>");

List Your Bookmarks / Forms

const forms = await oblax.forms.listMine("form");
console.log("My forms:", forms);

Create a Form via SDK

const created = await oblax.forms.create("form", {
  name: "contact_form",
  fields: [{ name: "email", type: "string", required: true }],
});

console.log("Created form:", created);

Error Handling

import {
  AuthenticationError,
  ValidationError,
  NotFoundError,
  PermissionError,
} from "@oblax/core";

try {
  const forms = await oblax.forms.listMine("form");
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("Login failed: token expired");
  } else if (err instanceof ValidationError) {
    console.error("Validation errors:", err.fields);
  } else if (err instanceof NotFoundError) {
    console.error("Form not found");
  } else if (err instanceof PermissionError) {
    console.error("Permission denied");
  }
}

Method 3: Your First API Call via REST

Oblax auto-generates REST endpoints from your modules. After scaffolding forms, your API endpoints are:

Operation	Endpoint	Example
List forms	`GET /v1/forms`	`curl -H "Authorization: Bearer <jwt>" https://api.oblax.io/v1/forms`
Get form by ID	`GET /v1/forms/{id}`	`curl -H "Authorization: Bearer <jwt>" https://api.oblax.io/v1/forms/f2837hfd17q3phc3`
Create form	`POST /v1/forms`	`curl -X POST -H "Authorization: Bearer <jwt>" -H "Content-Type: application/json" -d '{"name":"contact_form","fields":[{"name":"email","type":"string","required":true}]}' https://api.oblax.io/v1/forms`
Update form	`PUT /v1/forms/{id}`	`curl -X PUT -H "Authorization: Bearer <jwt>" -H "Content-Type: application/json" -d '{"name":"contact_form"}' https://api.oblax.io/v1/forms/f2837hfd17q3phc3`
Delete form	`DELETE /v1/forms/{id}`	`curl -X DELETE -H "Authorization: Bearer <jwt>" https://api.oblax.io/v1/forms/f2837hfd17q3phc3`

Authentication header: Always include Authorization: Bearer <your-jwt>. The JWT realm claim determines which endpoints accept the token.

API Response Format

All Oblax API responses follow a consistent structure:

Successful Response

{
  "success": true,
  "data": { "id": "f2837hfd17q3phc3", "name": "contact_form" },
  "meta": {
    "requestId": "rq_abc123",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "fields": { "email": ["Required"] }
  }
}

HTTP Status Codes:

Code	Meaning
`200`	OK — request succeeded
`201`	Created — new resource was created
`400`	Bad Request — invalid input
`401`	Unauthorized — missing or invalid JWT
`403`	Forbidden — insufficient role for the realm
`404`	Not Found — resource doesn’t exist
`422`	Unprocessable Entity — validation errors
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error

Usage

Your First API Call — Complete Workflow

Here’s the complete end-to-end flow:

obx login
obx app forms list
obx app forms get f2837hfd17q3phc3
obx app forms push init
obx app forms pull f2837hfd17q3phc3
obx app forms delete f2837hfd17q3phc3

Next Steps

You’ve made your first API call. Now explore:

Your First CLI Command — deeper CLI workflows and TUI patterns
Your First SDK Call — JavaScript/TypeScript integration
Run and Deploy — production deployment strategies