Authentication

All Sandbox API requests require authentication to ensure secure access to isolated environments.

Authentication Token

Every sandbox instance is created with a unique authentication token. This token must be included in all API requests.

Token Format

Bearer <your-token-here>

Where to Get Your Token

Tokens are provided when you:

Create a new sandbox instance
Request access to an existing sandbox
Receive it from the Oblien dashboard

⚠️ Warning: Never share your sandbox token. It provides full access to your isolated environment.

Making Authenticated Requests

Using the SDK

import { SandboxClient } from '@oblien/sandbox-sdk';

const sandbox = new SandboxClient({
  baseURL: 'https://sandbox.oblien.com:55872',
  token: process.env.SANDBOX_TOKEN // Store securely
});

// All requests are automatically authenticated
const files = await sandbox.files.list({ dirPath: '/opt/app' });

Using HTTP Headers

POST /files/list HTTP/1.1
Host: sandbox.oblien.com:55872
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "dirPath": "/opt/app"
}

Using cURL

curl -X POST https://sandbox.oblien.com:55872/files/list \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"dirPath": "/opt/app"}'

Using Node.js fetch

const response = await fetch('https://sandbox.oblien.com:55872/files/list', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SANDBOX_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ dirPath: '/opt/app' })
});

const data = await response.json();

WebSocket Authentication

WebSocket connections also require authentication:

Query Parameter

const ws = new WebSocket(
  'wss://sandbox.oblien.com:55872?token=YOUR_TOKEN_HERE'
);

Using SDK

// SDK handles WebSocket auth automatically
const ws = await sandbox.websocket.connect();

ws.on('message', (data) => {
  console.log('Received:', data);
});

Security Best Practices

1. Store Tokens Securely

Never hardcode tokens:

// ❌ Bad - token in code
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

// ✅ Good - token in environment variable
const token = process.env.SANDBOX_TOKEN;

2. Use Environment Variables

# .env file
SANDBOX_TOKEN=your-token-here
SANDBOX_URL=https://sandbox.oblien.com:55872

// Load from environment
import dotenv from 'dotenv';
dotenv.config();

const sandbox = new SandboxClient({
  baseURL: process.env.SANDBOX_URL,
  token: process.env.SANDBOX_TOKEN
});

3. Rotate Tokens Regularly

Tokens should be rotated periodically for security:

Every 30 days for production
Every 7 days for development
Immediately if compromised

4. Use HTTPS Only

Always use HTTPS endpoints:

// ✅ Good
const baseURL = 'https://sandbox.oblien.com:55872';

// ❌ Bad - insecure
const baseURL = 'http://sandbox.oblien.com:55872';

5. Limit Token Permissions

ℹ️ Info: Role-based access control (RBAC) for sandbox tokens is coming soon.

Token Scopes (Coming Soon)

Future support for scoped tokens:

{
  "token": "...",
  "scopes": [
    "files:read",
    "files:write",
    "git:read",
    "terminal:execute"
  ]
}

Error Responses

401 Unauthorized

Missing or invalid token:

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token"
}

Solution: Check that your token is valid and correctly formatted in the Authorization header.

403 Forbidden

Token doesn't have required permissions:

{
  "success": false,
  "error": "Forbidden",
  "message": "Token does not have required permissions"
}

Solution: Ensure your token has the necessary scopes for the operation.

Token Management

Validating Your Token

Test if your token is valid:

// Using SDK
const isValid = await sandbox.auth.validate();

if (isValid) {
  console.log('Token is valid');
} else {
  console.log('Token is invalid or expired');
}

GET /auth/validate HTTP/1.1
Host: sandbox.oblien.com:55872
Authorization: Bearer YOUR_TOKEN_HERE

Token Expiration

Tokens are valid for:

Development: 7 days
Production: 30 days
Custom: Configurable per instance

Need Help?

Review Quick Start for basic usage
Check File Operations for API examples
See WebSocket for real-time authentication

On this page