Internal API Access

Manage the workspace's internal server and access tokens. This is the Oblien API side of the Workspace Internal API - use these endpoints to enable the server, get tokens, and control access before making calls to workspace.oblien.com.

Server status

Check if the internal server is enabled and running.

const status = await ws.apiAccess.status('ws_a1b2c3d4');

console.log(status.enabled);  // true
console.log(status.running);  // true

GET /workspace/:workspaceId/internal-api-access

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

Enable server

Enable the internal HTTP server on port 9990 inside the workspace VM. Returns a signed Gateway JWT for accessing the Internal API at workspace.oblien.com.

This automatically adds port 9990 to the workspace's ingress_ports if not already present.

For gateway access to work, the workspace must also have public_access: true in its network configuration. This allows the gateway to reach the VM through the firewall. Enable it via the Network API if not already set.

const result = await ws.apiAccess.enable('ws_a1b2c3d4');

console.log(result.token); // Gateway JWT - use with workspace.oblien.com

POST /workspace/:workspaceId/internal-api-access/enable

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

Response

{
  "success": true,
  "enabled": true,
  "token": "eyJhbG..."
}

The returned token is a short-lived Gateway JWT (~1 hour) that you use as Authorization: Bearer <token> when calling workspace.oblien.com endpoints.

Disable server

Disable the internal server.

await ws.apiAccess.disable('ws_a1b2c3d4');

POST /workspace/:workspaceId/internal-api-access/disable

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

Response

{
  "success": true,
  "enabled": false
}

Rotate token

Rotate the connection token and return a fresh Gateway JWT. Use this to invalidate old tokens.

const result = await ws.apiAccess.rotateToken('ws_a1b2c3d4');
console.log(result.token); // Fresh gateway JWT

POST /workspace/:workspaceId/internal-api-access/token

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

Response

{
  "success": true,
  "token": "eyJhbG..."
}

Raw token

Get the raw connection token and VM private IP. Use this for workspace-to-workspace communication over the internal network, bypassing the edge gateway.

Direct workspace-to-workspace calls require a private link between the two workspaces. Without a link, the target's firewall blocks the connection regardless of having a valid token.

const raw = await ws.apiAccess.rawToken('ws_a1b2c3d4');

console.log(raw.token);  // hex connection token
console.log(raw.ip);     // "10.x.x.x"
console.log(raw.port);   // 9990

GET /workspace/:workspaceId/internal-api-access/token/raw

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

Response

{
  "success": true,
  "token": "a1b2c3d4e5f6...",
  "ip": "10.40.0.5",
  "port": 9990
}

Use the raw token with Authorization: Bearer <token> when calling the target workspace directly:

curl "http://10.40.0.5:9990/files?path=/app" \
  -H "Authorization: Bearer a1b2c3d4e5f6..."

Requires a private link between the two workspaces.

Reconnect

Close existing WebSocket connections and re-issue the connection token. Functionally an alias for Rotate token with additional WebSocket cleanup.

POST /workspace/:workspaceId/internal-api-access/reconnect

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

Workspace access token

Generate a long-lived (30 day) workspace-scoped access token. This token is designed for SDKs, MCP servers, and long-running integrations that need persistent access without frequent renewal.

const result = await ws.apiAccess.workspaceToken('ws_a1b2c3d4');
console.log(result.token); // 30-day access token

POST /workspace/:workspaceId/internal-api-access/workspace

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

Response

{
  "success": true,
  "token": "eyJhbG..."
}

Unlike the Gateway JWT (~1 hour), this token lasts 30 days and is suitable for SDKs, MCP servers, and long-running integrations. It does not contain the VM IP - the SDK resolves routing automatically.

Endpoint summary

Endpoint	Method	Description
`/internal-api-access`	`GET`	Server status
`/internal-api-access/enable`	`POST`	Enable server, get Gateway JWT
`/internal-api-access/disable`	`POST`	Disable server
`/internal-api-access/token`	`POST`	Rotate token, get fresh Gateway JWT
`/internal-api-access/token/raw`	`GET`	Raw connection token + VM IP
`/internal-api-access/reconnect`	`POST`	Close WS + rotate token
`/internal-api-access/workspace`	`POST`	30-day workspace access token

On this page