Authentication

Every request to the Oblien API must be authenticated. There are two methods depending on where your code runs.

Server-side: API Key Authentication

Use your Client ID and Client Secret as request headers. This is the standard method for backend services, scripts, and the SDK.

Getting your credentials

1. Go to Dashboard → Settings → API Credentials
2. Click Create API Key
3. Copy both the Client ID and Client Secret

Using API keys

import Oblien from 'oblien';

const client = new Oblien({
  clientId: process.env.OBLIEN_CLIENT_ID!,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET!,
});

const response = await fetch('https://api.oblien.com/workspace', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json',
  },
});

curl https://api.oblien.com/workspace \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Required headers

API key scopes

When creating an API key, you can restrict it to a specific scope:

Namespace and workspace scoped keys enforce access server-side — workspace lists are filtered, creates are forced into the bound namespace, and cross-namespace access is blocked with 403.

Scoped tokens (short-lived JWTs)

For SaaS platforms, use Scoped Tokens instead of creating separate API keys for each end-user. Your backend issues a short-lived JWT (max 1 hour) bound to a namespace or workspace, and hands it to the end-user.

// Backend: issue a namespace-scoped token
const { token } = await client.tokens.create({
  scope: 'namespace',
  namespace: 'tenant-abc',
  ttl: 900,
});

// Frontend: use the token
const userClient = new Oblien({ token });
const workspaces = await userClient.workspaces.list();

See the full Scoped Tokens guide for details.

Client-side: Workspace Tokens

For browser or client-side applications, never expose your API secret. Instead, generate a scoped workspace token from your backend and pass it to the client.

Generate a token (server-side)

// Enable Runtime API and get a gateway JWT
const result = await client.workspaces.apiAccess.enable(workspaceId);
// { success: true, token: "eyJhbG..." }

// Or rotate the token
const rotated = await client.workspaces.apiAccess.rotateToken(workspaceId);

curl -X POST https://api.oblien.com/workspace/{id}/runtime-api-access/token \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Use the token (client-side)

// Pass this to your frontend
const response = await fetch('https://api.oblien.com/workspace/{id}/stats', {
  headers: {
    'Authorization': `Bearer ${workspaceToken}`,
  },
});

Workspace tokens:

• Are scoped to a single workspace
• Expire after 30 days
• Can be refreshed by calling the token endpoint again

Environment variables

We recommend storing credentials in environment variables:

# .env (never commit this file)
OBLIEN_CLIENT_ID=your-client-id
OBLIEN_CLIENT_SECRET=your-client-secret

// Load with dotenv or your framework's env support
import Oblien from 'oblien';

const client = new Oblien({
  clientId: process.env.OBLIEN_CLIENT_ID!,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET!,
});

Security best practices

• Never commit API secrets to version control
• Never expose secrets in frontend/client-side code
• Use workspace tokens for any browser-facing features
• Rotate keys periodically from the dashboard
• Use separate keys for development and production
• Set namespace quotas to limit per-environment spending

Rate limits

Rate limits vary by plan. See the Pricing page for current limits.

When you hit the rate limit, the API returns 429 Too Many Requests with a Retry-After header.

Next steps

• SDK Setup - Configure the SDK client
• API Reference - Explore all endpoints
• Pricing - Compare plans and limits