Connect a frontend

Every Apso backend exposes a standard REST API. JavaScript and TypeScript applications can also use @apso/sdk for fluent queries and mutations.

Request lifecycleOne request, with every backend boundary visible.

Authenticated

01ClientServer component, mobile app, or service
02SDK or RESTTyped operation and validated payload
03IdentitySession, JWT, or API key context
04Tenant scopeAuthorization and row boundary
05ServiceGenerated route, product logic, and database

Keep privileged credentials on the server and pass only verified identity and tenant context into the generated service.

Choose a connection pattern

Pattern	Use it when	Credential location
Server-side SDK	Next.js BFF, server-rendered app, worker, or trusted backend	Server environment variables
Browser or mobile REST	The user has an end-user token and the API permits the client origin	Secure cookie or platform credential storage
Route proxy	The frontend needs a narrow API and service credentials must stay private	Proxy server only

Keep an Apso service API key on the server. Do not place it in NEXT_PUBLIC_*, VITE_*, a mobile bundle, or browser storage.

Framework guides

Build a BFF with Server Components, Server Actions, and route handlers

Next.js

Call a BFF or use end-user REST authentication from a browser client

React

Connect a mobile client and store user credentials securely

React Native

Use a Dart HTTP client with the generated REST endpoints

Flutter

Server-side SDK setup


npm install @apso/sdk

lib/apso.ts


import { ApsoClientFactory } from '@apso/sdk';
 
export const apso = ApsoClientFactory.getClient({
  baseURL: process.env.APSO_API_URL!,
  apiKey: process.env.APSO_API_KEY!,
});

services/projects.ts


import { apso } from '../lib/apso';
 
export function listActiveProjects() {
  return apso.entity('Projects')
    .where({ status: { $eq: 'Active' } })
    .orderBy({ created_at: 'DESC' })
    .findMany();
}

Direct REST request

Use direct HTTP when the client has an end-user access token:


const response = await fetch(`${API_URL}/Project?limit=20`, {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});
 
if (!response.ok) {
  throw new Error(`Project request failed: ${response.status}`);
}
 
const projects = await response.json();

Before you connect

Confirm the API base URL and health endpoint.
Choose service API keys for trusted servers or end-user tokens for clients.
Configure CORS for each browser origin that can reach the API.
Verify tenant context is derived from a trusted identity claim or server-side lookup.
Handle 401, 403, 404, 409, 422, and 5xx responses explicitly.