API REFERENCE

REST API for session management, authentication, and resource control.

AUTHENTICATION

Include your API key in the Authorization header for all API requests.

$ curl -X POST https://api.astack.dev/api/v1/sessions \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"end_user_id": "user_123"}'

SECURITY BEST PRACTICES

▶Never expose API keys in client-side code — use session tokens instead
▶Use environment variables to store keys
▶Create scoped keys with minimum required permissions
▶Rotate keys regularly and monitor usage

API KEY SCOPES

API keys can be scoped to limit access. Create and manage keys from the dashboard or via the Server SDK.

sessions:readRead session details and status

sessions:writeCreate and terminate sessions

users:readRead user profiles

users:writeCreate, update, and delete users

billing:readRead usage, invoices, and billing info

billing:writeRecord usage and set alerts

workers:readRead worker status and metrics

workers:writeRequest worker scaling

admin:allFull admin access (audit logs, performance)

LEGACY PERMISSIONS

Keys created via the dashboard use these permission flags:

session_createCreate new sessions

session_manageManage existing sessions

usage_readAccess usage metrics

RATE LIMITS

DEFAULT LIMITS

Requests per minute100

Requests per hour1,000

Concurrent sessions10

Rate limits can be customized per API key via the Server SDK or dashboard. Contact support for higher limits.

SESSION ENDPOINTS

CREATE SESSION

POST /api/v1/sessions

{
  "end_user_id": "user_123",
  "connection_type": "websocket",
  "quality": "high",
  "features": ["vision"],
  "metadata": { "source": "web" }
}

Returns a session object with session_token and worker_url for WebSocket connection.

GET SESSION

GET /api/v1/sessions/:sessionId

TERMINATE SESSION

DELETE /api/v1/sessions/:sessionId

SESSION LIFECYCLE

PENDINGSession created, waiting for connection

ACTIVEUser connected, conversation in progress

COMPLETEDSession ended successfully

FAILEDSession ended due to error

EXPIREDSession TTL exceeded

SERVER INTEGRATION

END-TO-END EXAMPLE

Your backend creates a session and returns the connection details to the client.

import express from 'express';
import { AStackSDK, authMiddleware, errorHandler } from '@aether-stack-dev/developer-sdk';

const app = express();
const sdk = new AStackSDK({
  apiKey: process.env.ASTACK_API_KEY,
  apiSecret: process.env.ASTACK_API_SECRET,
});

app.use(express.json());
app.use('/api', authMiddleware(sdk));

app.post('/api/start-session', async (req, res) => {
  const { session } = await sdk.createSession(req.body.userId, {
    quality: 'high',
  });
  const sessionToken = await sdk.generateSessionToken(session.id);
  res.json({ sessionToken, workerUrl: session.node_id });
});

app.use(errorHandler());
app.listen(3000);