Accounts API

Reference for managing connected social media accounts.

Overview

Accounts represent your connected social media profiles. Each account is associated with a platform and contains encrypted credentials for authentication.

List Accounts

Get all your connected accounts.

Endpoint:

GET /api/accounts

Query Parameters:

platform (optional) - Filter by platform (twitter, xueqiu, eastmoney, tonghuashun)
status (optional) - Filter by status (active, error, pending)

Example:

bash

# Get all accounts
curl https://api.browserman.run/api/accounts \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get Twitter accounts only
curl https://api.browserman.run/api/accounts?platform=twitter \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get accounts with errors
curl https://api.browserman.run/api/accounts?status=error \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": "acc_abc123",
        "name": "my-twitter",
        "platform": "twitter",
        "status": "active",
        "authMethod": "oauth",
        "createdAt": "2024-01-10T08:00:00Z",
        "lastUsedAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "acc_def456",
        "name": "my-xueqiu",
        "platform": "xueqiu",
        "status": "active",
        "authMethod": "credentials",
        "createdAt": "2024-01-11T09:00:00Z",
        "lastUsedAt": "2024-01-15T09:15:00Z"
      },
      {
        "id": "acc_ghi789",
        "name": "work-twitter",
        "platform": "twitter",
        "status": "error",
        "authMethod": "oauth",
        "createdAt": "2024-01-12T10:00:00Z",
        "lastUsedAt": "2024-01-14T16:20:00Z",
        "error": {
          "code": "AUTHENTICATION_FAILED",
          "message": "OAuth token expired. Please reconnect."
        }
      }
    ],
    "total": 3
  }
}

Get Account Details

Get detailed information about a specific account.

Endpoint:

GET /api/accounts/:accountId

Example:

bash

curl https://api.browserman.run/api/accounts/acc_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json

{
  "success": true,
  "data": {
    "id": "acc_abc123",
    "name": "my-twitter",
    "platform": "twitter",
    "status": "active",
    "authMethod": "oauth",
    "createdAt": "2024-01-10T08:00:00Z",
    "lastUsedAt": "2024-01-15T10:30:00Z",
    "stats": {
      "totalTasks": 150,
      "successfulTasks": 145,
      "failedTasks": 5,
      "lastTaskAt": "2024-01-15T10:30:00Z"
    },
    "settings": {
      "preferredEngine": "lite",
      "timeout": 120000
    },
    "metadata": {
      "purpose": "personal",
      "notes": "Main personal Twitter account"
    }
  }
}

OAuth Authorization

Initiate OAuth flow to connect an account.

Endpoint:

POST /api/accounts/oauth/authorize

Request:

json

{
  "platform": "twitter",
  "accountName": "my-twitter",
  "redirectUrl": "https://your-app.com/oauth/callback"
}

Example:

bash

curl -X POST https://api.browserman.run/api/accounts/oauth/authorize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "twitter",
    "accountName": "my-twitter",
    "redirectUrl": "https://your-app.com/oauth/callback"
  }'

Response:

json

{
  "success": true,
  "data": {
    "authorizationUrl": "https://twitter.com/oauth/authorize?oauth_token=...",
    "oauthToken": "temp_oauth_token_123",
    "expiresAt": "2024-01-15T10:45:00Z"
  }
}

Flow:

Request authorization URL from Browserman
Redirect user to the authorization URL
User authorizes on the platform
Platform redirects back to your redirectUrl with OAuth token
Complete the authorization (next endpoint)

Complete OAuth Authorization

Complete the OAuth flow after user authorization.

Endpoint:

POST /api/accounts/oauth/callback

Request:

json

{
  "oauthToken": "temp_oauth_token_123",
  "oauthVerifier": "oauth_verifier_from_platform"
}

Example:

bash

curl -X POST https://api.browserman.run/api/accounts/oauth/callback \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "oauthToken": "temp_oauth_token_123",
    "oauthVerifier": "xyz789"
  }'

Response:

json

{
  "success": true,
  "data": {
    "accountId": "acc_abc123",
    "name": "my-twitter",
    "platform": "twitter",
    "status": "active",
    "authMethod": "oauth",
    "createdAt": "2024-01-15T10:40:00Z"
  }
}

Create Account with Credentials

Manually create an account with username/password credentials.

Endpoint:

POST /api/accounts

Request:

json

{
  "platform": "xueqiu",
  "accountName": "my-xueqiu",
  "credentials": {
    "username": "user@example.com",
    "password": "secure_password"
  },
  "metadata": {
    "purpose": "trading",
    "notes": "Primary Xueqiu account"
  }
}

Example:

bash

curl -X POST https://api.browserman.run/api/accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "xueqiu",
    "accountName": "my-xueqiu",
    "credentials": {
      "username": "user@example.com",
      "password": "secure_password"
    }
  }'

Response:

json

{
  "success": true,
  "data": {
    "accountId": "acc_def456",
    "name": "my-xueqiu",
    "platform": "xueqiu",
    "status": "active",
    "authMethod": "credentials",
    "createdAt": "2024-01-15T10:45:00Z"
  }
}

Security

Credentials are encrypted before storage. However, OAuth is recommended when available for better security.

Update Account

Update account settings or metadata.

Endpoint:

PATCH /api/accounts/:accountId

Request:

json

{
  "name": "new-account-name",
  "settings": {
    "preferredEngine": "full",
    "timeout": 180000
  },
  "metadata": {
    "purpose": "business",
    "notes": "Updated notes"
  }
}

Example:

bash

curl -X PATCH https://api.browserman.run/api/accounts/acc_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "preferredEngine": "full"
    }
  }'

Response:

json

{
  "success": true,
  "data": {
    "accountId": "acc_abc123",
    "name": "my-twitter",
    "platform": "twitter",
    "status": "active",
    "settings": {
      "preferredEngine": "full",
      "timeout": 120000
    },
    "updatedAt": "2024-01-15T10:50:00Z"
  }
}

Update Account Credentials

Update credentials for a credential-based account.

Endpoint:

POST /api/accounts/:accountId/credentials

Request:

json

{
  "username": "new_username@example.com",
  "password": "new_secure_password"
}

Example:

bash

curl -X POST https://api.browserman.run/api/accounts/acc_def456/credentials \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "new_secure_password"
  }'

Response:

json

{
  "success": true,
  "data": {
    "accountId": "acc_def456",
    "status": "active",
    "updatedAt": "2024-01-15T10:55:00Z"
  }
}

Reconnect OAuth Account

Reconnect an OAuth account with expired or invalid tokens.

Endpoint:

POST /api/accounts/:accountId/reconnect

Example:

bash

curl -X POST https://api.browserman.run/api/accounts/acc_abc123/reconnect \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json

{
  "success": true,
  "data": {
    "authorizationUrl": "https://twitter.com/oauth/authorize?oauth_token=...",
    "oauthToken": "temp_oauth_token_456",
    "expiresAt": "2024-01-15T11:10:00Z"
  }
}

Follow the same OAuth flow as initial authorization.

Delete Account

Permanently delete an account and all its data.

Endpoint:

DELETE /api/accounts/:accountId

Example:

bash

curl -X DELETE https://api.browserman.run/api/accounts/acc_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json

{
  "success": true,
  "data": {
    "accountId": "acc_abc123",
    "deletedAt": "2024-01-15T11:00:00Z"
  }
}

Irreversible

Deleting an account is permanent and cannot be undone. All associated data will be removed.

Account Status

Accounts can be in various states:

Active

Account is connected and ready to use.

json

{
  "status": "active"
}

Error

Account has an authentication or connection issue.

json

{
  "status": "error",
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "OAuth token expired. Please reconnect.",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Common error codes:

AUTHENTICATION_FAILED - Credentials invalid or expired
ACCOUNT_SUSPENDED - Platform suspended the account
RATE_LIMITED - Account is rate limited
CONNECTION_ERROR - Cannot connect to platform

Pending

OAuth authorization is in progress.

json

{
  "status": "pending",
  "oauthToken": "temp_oauth_token_123",
  "expiresAt": "2024-01-15T10:45:00Z"
}

Account Settings

Customize account behavior with settings:

Preferred Engine

json

{
  "settings": {
    "preferredEngine": "full"
  }
}

Options: lite (default) or full

Timeout

json

{
  "settings": {
    "timeout": 180000
  }
}

Timeout in milliseconds (max: 600000 for lite, 900000 for full)

Proxy Settings

json

{
  "settings": {
    "proxy": {
      "enabled": true,
      "region": "us-east"
    }
  }
}

Account Metadata

Store custom metadata with accounts:

json

{
  "metadata": {
    "purpose": "personal",
    "category": "social",
    "notes": "Main Twitter account for personal use",
    "tags": ["personal", "active"],
    "customField": "any value"
  }
}

Metadata is arbitrary JSON and doesn't affect functionality.

Best Practices

1. Use Descriptive Names

javascript

// Good
{ accountName: "personal-twitter" }
{ accountName: "work-brand-official" }
{ accountName: "xueqiu-trading" }

// Bad
{ accountName: "account1" }
{ accountName: "test" }
{ accountName: "a" }

2. Prefer OAuth

javascript

// Recommended
await createOAuthAccount('twitter', 'my-twitter');

// Less secure
await createCredentialsAccount('twitter', 'my-twitter', {
  username: 'user',
  password: 'pass'
});

3. Monitor Account Health

javascript

async function checkAccountHealth() {
  const accounts = await listAccounts();

  for (const account of accounts) {
    if (account.status === 'error') {
      console.warn(`Account ${account.name} has issues:`, account.error);
      await reconnectAccount(account.id);
    }
  }
}

// Run daily
setInterval(checkAccountHealth, 24 * 60 * 60 * 1000);

4. Handle Reconnection

javascript

async function executeWithReconnect(accountId, task) {
  try {
    return await executeTask(task);
  } catch (error) {
    if (error.code === 'AUTHENTICATION_FAILED') {
      await reconnectAccount(accountId);
      return await executeTask(task);
    }
    throw error;
  }
}

5. Organize with Metadata

javascript

await updateAccount(accountId, {
  metadata: {
    purpose: 'business',
    team: 'marketing',
    priority: 'high',
    notes: 'Primary brand account'
  }
});

// Later, filter by metadata
const marketingAccounts = accounts.filter(
  acc => acc.metadata?.team === 'marketing'
);

Account Limits

Limits vary by plan:

Free: 5 accounts total
Pro: 50 accounts total
Enterprise: Unlimited

Per-platform limits:

Twitter: Up to 10 accounts (Pro), unlimited (Enterprise)
Xueqiu: Up to 5 accounts (Pro), unlimited (Enterprise)
Other platforms: Up to 5 accounts (Pro), unlimited (Enterprise)

Accounts API ​

Overview ​

List Accounts ​

Get Account Details ​

OAuth Authorization ​

Complete OAuth Authorization ​

Create Account with Credentials ​

Update Account ​

Update Account Credentials ​

Reconnect OAuth Account ​

Delete Account ​

Account Status ​

Active ​

Error ​

Pending ​

Account Settings ​

Preferred Engine ​

Timeout ​

Proxy Settings ​

Account Metadata ​

Best Practices ​

1. Use Descriptive Names ​

2. Prefer OAuth ​

3. Monitor Account Health ​

4. Handle Reconnection ​

5. Organize with Metadata ​

Account Limits ​

Next Steps ​

Accounts API

Overview

List Accounts

Get Account Details

OAuth Authorization

Complete OAuth Authorization

Create Account with Credentials

Update Account

Update Account Credentials

Reconnect OAuth Account

Delete Account

Account Status

Active

Error

Pending

Account Settings

Preferred Engine

Timeout

Proxy Settings

Account Metadata

Best Practices

1. Use Descriptive Names

2. Prefer OAuth

3. Monitor Account Health

4. Handle Reconnection

5. Organize with Metadata

Account Limits

Next Steps