Skip to main content
The Wassist SDK uses token-based authentication. Every request to the API includes your authentication token in the headers.

​
Getting Your Token

​
From the Dashboard

  1. Log in to wassist.app
  2. Go to Settings → API Keys
  3. Click Create API Key
  4. Copy your token (it won’t be shown again)
Treat your API token like a password. Never expose it in client-side code or commit it to version control.

​
Via API (Programmatic)

If you’re building an application where users log in with their Wassist credentials, you can obtain tokens programmatically through the authentication flow.

​
Using Your Token

​
At Client Creation

The most common approach—pass the token when creating the client: 
import { createWassistClient } from '@wassist/sdk';

const client = createWassistClient({
  baseUrl: 'https://api.wassist.app/api/v1/',
  authToken: process.env.WASSIST_TOKEN,
});

​
Setting Token Later

For applications where authentication state changes: 
const client = createWassistClient({
  baseUrl: 'https://api.wassist.app/api/v1/',
});

// When user logs in
client.setAuthToken(userToken);

// Make authenticated requests
const agents = await client.agents.list();

// When user logs out
client.clearAuthToken();

​
How Authentication Works

The SDK automatically adds the token to every request: 
Authorization: Token your-auth-token-here
You don’t need to manage headers manually—the SDK handles this.

​
Handling Authentication Errors

When a request returns a 401 Unauthorized error:
  1. The SDK calls your onAuthError callback (if provided)
  2. Throws an Error with message “Unauthorized”

​
Setting Up Error Handling

const client = createWassistClient({
  baseUrl: 'https://api.wassist.app/api/v1/',
  authToken: storedToken,
  onAuthError: () => {
    // Clear invalid token
    localStorage.removeItem('wassist_token');
    
    // Redirect to login
    window.location.href = '/login';
  },
});

​
Try-Catch Handling

try {
  const agent = await client.agents.get(agentId);
} catch (error) {
  if (error.message === 'Unauthorized') {
    // Token is invalid or expired
    await refreshToken();
  } else {
    // Other error
    throw error;
  }
}

​
Token Best Practices

Server-side: Use environment variables or a secrets manager.
# .env (never commit this file)
WASSIST_TOKEN=your-secret-token
Client-side: Store in memory or secure storage, never in localStorage for sensitive applications.
Periodically rotate your API keys:
  1. Create a new API key
  2. Update your application to use the new key
  3. Verify everything works
  4. Revoke the old key
Create separate API keys for different purposes:
  • Production key (restricted access)
  • Development key (full access, test data only)
  • CI/CD key (limited to deployment tasks)
API tokens should never be in browser-accessible code:Bad:
// This exposes your token to anyone viewing source
const client = createWassistClient({
  baseUrl: 'https://api.wassist.app/api/v1/',
  authToken: 'sk_live_abc123', // DON'T DO THIS
});
Good:
// Proxy requests through your backend
const response = await fetch('/api/wassist/agents');

​
Server-Side Proxy Pattern

For browser applications, proxy API calls through your server: 
// Your backend (e.g., Next.js API route)
// pages/api/agents.ts

import { createWassistClient } from '@wassist/sdk';

export default async function handler(req, res) {
  const client = createWassistClient({
    baseUrl: process.env.WASSIST_API_URL,
    authToken: process.env.WASSIST_TOKEN,
  });
  
  try {
    const agents = await client.agents.list();
    res.json(agents);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

// Your frontend
async function getAgents() {
  const response = await fetch('/api/agents');
  return response.json();
}

​
Multi-Tenant Authentication

If your application serves multiple users, each with their own Wassist account: 
// Create a client for each request/user
function getClientForUser(userToken: string) {
  return createWassistClient({
    baseUrl: 'https://api.wassist.app/api/v1/',
    authToken: userToken,
    onAuthError: () => {
      // Handle per-user auth failure
    },
  });
}

// In your request handler
app.get('/agents', async (req, res) => {
  const userToken = req.session.wassistToken;
  const client = getClientForUser(userToken);
  
  const agents = await client.agents.list();
  res.json(agents);
});

​
Troubleshooting

  • Verify your token is correct (no extra spaces or characters)
  • Check that the token hasn’t been revoked
  • Ensure you’re using the right environment’s token (prod vs dev)
  • Confirm authToken is set before making requests
  • Check that setAuthToken() was called if setting after creation
  • Verify the token value isn’t empty or undefined

​
Next Steps

Agents

Create and manage agents.

Error Handling

Handle errors gracefully.