Accounts Action - Social Media Management API

Manage connected social media accounts programmatically. Add, remove, edit, and configure accounts for X, BlueSky, and Mastodon.

Syntax

statuz://accounts?action={action}&platform={platform}&[parameters]

Parameters

ParameterTypeDescriptionExample
actionstringRequired - Action to perform: add, remove, edit, set-defaultadd
platformstringRequired - Platform: x, bluesky, mastodonx
idstringAccount ID (for identification)account-123
namestringAccount username/handlejohndoe
nicknamestringAccount nicknameWork%20Account
set-nicknamestringNew nickname (for edit action)Personal
set-enabledbooleanEnable/disable accounttrue
instancestringMastodon instance URLfosstodon.org
autoConnectbooleanAuto-trigger OAuth (for add action)true

Important: Nicknames are platform-scoped. You can use the same nickname on different platforms without conflicts.

Actions

Add Account

Navigate to the account connection screen and optionally trigger OAuth automatically.

Basic Add

# Add X account
open "statuz://accounts?action=add&platform=x"

# Add BlueSky account 
open "statuz://accounts?action=add&platform=bluesky"

# Add Mastodon account (defaults to mastodon.social)
open "statuz://accounts?action=add&platform=mastodon"

Add with Custom Instance

For Mastodon, specify a custom instance:

# Add account on fosstodon
open "statuz://accounts?action=add&platform=mastodon&instance=fosstodon.org"

# Add account on mas.to
open "statuz://accounts?action=add&platform=mastodon&instance=mas.to"

Control Auto-Connection

By default, the OAuth flow triggers automatically. To only show the form:

# Show form without auto-connecting
open "statuz://accounts?action=add&platform=mastodon&autoConnect=false"

Remove Account

Disconnect and remove an account. Identify the account using one of: id, name, or nickname.

# Remove by username
open "statuz://accounts?action=remove&platform=x&name=johndoe"

# Remove by ID
open "statuz://accounts?action=remove&platform=bluesky&id=account-123"

# Remove by nickname (URL-encoded)
NICKNAME=$(printf %s "Work Account" | jq -sRr @uri)
open "statuz://accounts?action=remove&platform=x&nickname=$NICKNAME"

Edit Account

Modify account settings: nickname and enabled status.

Note: Credentials cannot be modified via URL scheme for security. OAuth must be done through the app's secure UI.

Change Nickname

# Edit by username
NICKNAME=$(printf %s "Personal Account" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=x&name=johndoe&set-nickname=$NICKNAME"

# Edit by ID
NICKNAME=$(printf %s "Work Account" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=bluesky&id=account-456&set-nickname=$NICKNAME"

Enable/Disable Account

# Disable account temporarily
open "statuz://accounts?action=edit&platform=x&name=johndoe&set-enabled=false"

# Re-enable account
open "statuz://accounts?action=edit&platform=x&name=johndoe&set-enabled=true"

Edit Multiple Fields

# Change nickname and enable
NICKNAME=$(printf %s "Main Account" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=bluesky&name=user&set-nickname=$NICKNAME&set-enabled=true"

Set Default Account

Set which account should be the default for a platform.

# Set default by username
open "statuz://accounts?action=set-default&platform=x&name=johndoe"

# Set default by nickname
NICKNAME=$(printf %s "Work Account" | jq -sRr @uri)
open "statuz://accounts?action=set-default&platform=bluesky&nickname=$NICKNAME"

# Set default by ID
open "statuz://accounts?action=set-default&platform=mastodon&id=account-789"

Platform-Specific Examples

X (Twitter) Accounts

#!/bin/bash

# Add X account
open "statuz://accounts?action=add&platform=x"

# Set nickname for identification
NICKNAME=$(printf %s "Personal Twitter" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=x&name=myhandle&set-nickname=$NICKNAME"

# Set as default
open "statuz://accounts?action=set-default&platform=x&name=myhandle"

BlueSky Accounts

#!/bin/bash

# Add BlueSky account
open "statuz://accounts?action=add&platform=bluesky"

# Edit nickname (use full handle)
NICKNAME=$(printf %s "Main Bluesky" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=bluesky&name=user.bsky.social&set-nickname=$NICKNAME"

Mastodon Accounts

#!/bin/bash

# Add account on specific instance
open "statuz://accounts?action=add&platform=mastodon&instance=mastodon.social"

# Add another instance
open "statuz://accounts?action=add&platform=mastodon&instance=fosstodon.org"

# Set default Mastodon account
open "statuz://accounts?action=set-default&platform=mastodon&name=user@mastodon.social"

Automation Workflows

Context Switching

Switch between work and personal accounts:

#!/bin/bash
# switch-work.sh

echo "Switching to work accounts..."

# Set work accounts as default
open "statuz://accounts?action=set-default&platform=x&nickname=Work%20X"
open "statuz://accounts?action=set-default&platform=bluesky&nickname=Work%20BlueSky"

# Disable personal accounts
open "statuz://accounts?action=edit&platform=x&nickname=Personal%20X&set-enabled=false"
open "statuz://accounts?action=edit&platform=bluesky&nickname=Personal%20BlueSky&set-enabled=false"

echo "Work accounts activated!"

#!/bin/bash
# switch-personal.sh

echo "Switching to personal accounts..."

# Set personal accounts as default
open "statuz://accounts?action=set-default&platform=x&nickname=Personal%20X"
open "statuz://accounts?action=set-default&platform=bluesky&nickname=Personal%20BlueSky"

# Enable personal accounts
open "statuz://accounts?action=edit&platform=x&nickname=Personal%20X&set-enabled=true"
open "statuz://accounts?action=edit&platform=bluesky&nickname=Personal%20BlueSky&set-enabled=true"

echo "Personal accounts activated!"

Bulk Account Management

#!/bin/bash
# cleanup-accounts.sh

# Disable all test accounts
TEST_ACCOUNTS=("test1" "test2" "test3")

for account in "${TEST_ACCOUNTS[@]}"; do
 echo "Disabling $account..."
 open "statuz://accounts?action=edit&platform=x&name=$account&set-enabled=false"
 sleep 0.5
done

echo "Test accounts disabled!"

Setup New Machine

#!/bin/bash
# setup-statuz-accounts.sh

echo "Setting up Statuz accounts..."

# Add all accounts
open "statuz://accounts?action=add&platform=x"
sleep 2
open "statuz://accounts?action=add&platform=bluesky"
sleep 2
open "statuz://accounts?action=add&platform=mastodon&instance=mastodon.social"
sleep 2

# Set nicknames (after OAuth completes)
read -p "Press enter after completing OAuth flows..."

# Configure nicknames
WORK_X=$(printf %s "Work Twitter" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=x&name=workhandle&set-nickname=$WORK_X"

PERSONAL_BS=$(printf %s "Personal BlueSky" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=bluesky&name=user.bsky.social&set-nickname=$PERSONAL_BS"

echo "Accounts configured!"

Account Identifiers

You can identify accounts using three methods:

1. Username/Handle

Platform-specific format:

• X: Just the handle (no @): johndoe

• BlueSky: Full handle with domain: user.bsky.social

• Mastodon: User@instance format: user@mastodon.social

# X
open "statuz://accounts?action=edit&platform=x&name=johndoe&..."

# BlueSky
open "statuz://accounts?action=edit&platform=bluesky&name=user.bsky.social&..."

# Mastodon
open "statuz://accounts?action=edit&platform=mastodon&name=user@instance.social&..."

2. Nickname

Custom name you've assigned to the account. Must be URL-encoded.

NICKNAME=$(printf %s "My Work Account" | jq -sRr @uri)
open "statuz://accounts?action=edit&platform=x&nickname=$NICKNAME&..."

Platform Scoping: Nicknames are scoped per platform. You can use "Work Account" on both X and BlueSky without conflicts.

3. Account ID (UUID)

Internal account identifier. Use the MCP accounts_list tool or Settings to find IDs.

open "statuz://accounts?action=edit&platform=x&id=550e8400-e29b-41d4-a716-446655440000&..."

Error Handling

Common errors and solutions:

Account Not Found

❌ Error: "Account not found"

Solutions:

• Verify the username/handle format is correct for the platform

• Check capitalization matches exactly

• For Mastodon, include the instance: user@instance.social

• Use the MCP accounts_list tool to see exact names

Invalid Platform

❌ Error: "Invalid platform"

Fix: Use x, bluesky, or mastodon (lowercase)

Duplicate Account

❌ Error: "Account already connected"

Fix: Use the edit action instead of add

Invalid Instance URL

❌ Error: "Invalid Mastodon instance"

Solutions:

• Verify the instance exists and is accessible

• Use just the domain: mastodon.social (not https://)

• Check for typos in the instance URL

Security Notes

Credentials Protection

Account passwords, tokens, and OAuth credentials are never exposed through the URL scheme:

✅ Can modify:

• Account nickname

• Enabled/disabled status

• Default account selection

❌ Cannot modify:

• OAuth tokens

• Account passwords

• API keys

• Secret keys

OAuth Requirement

Adding accounts requires OAuth authentication through Statuz's secure UI:

• URL scheme opens the connection screen

• User authenticates via OAuth in-app

• Credentials stored securely in macOS Keychain

• Never exposed to URL scheme or scripts

Platform Support

PlatformIdentifierFeatures
X (Twitter)xOAuth 1.0, multiple accounts (premium)
BlueSkyblueskyOAuth 2.0, handle-based auth
MastodonmastodonOAuth 2.0, custom instances

Best Practices

• Use nicknames for readable account management

• Scope nicknames per-platform to avoid confusion

• Test with one account before bulk operations

• Handle OAuth separately - scripts can't complete OAuth

• Wait between operations to avoid race conditions

• Verify account names before bulk removal

• Store configurations as scripts for repeatable setups

Integration Examples

Raycast Script

#!/usr/bin/env node
// @raycast.schemaVersion 1
// @raycast.title Switch to Work Accounts
// @raycast.mode silent

const { exec } = require('child_process');

const accounts = [
 { platform: 'x', nickname: 'Work Twitter' },
 { platform: 'bluesky', nickname: 'Work BlueSky' }
];

accounts.forEach(({ platform, nickname }) => {
 const encoded = encodeURIComponent(nickname);
 exec(`open "statuz://accounts?action=set-default&platform=${platform}&nickname=${encoded}"`);
});

Alfred Workflow

Set up keywords to switch account contexts:

# Keyword: work-accounts
open "statuz://accounts?action=set-default&platform=x&nickname=Work%20X"
open "statuz://accounts?action=set-default&platform=bluesky&nickname=Work%20BS"

# Keyword: personal-accounts 
open "statuz://accounts?action=set-default&platform=x&nickname=Personal%20X"
open "statuz://accounts?action=set-default&platform=bluesky&nickname=Personal%20BS"

Related

• Compose Action (/docs/url-scheme-compose) - Create posts with specific accounts

• Schedule Action (/docs/url-scheme-schedule) - Schedule to specific platforms

• MCP Accounts Tools (/docs/mcp-tools#account-management) - AI-powered account management

Try Statuz today,
it's free.
Download for macOS (/download)