Auth Endpoints

Last updated: January 26, 2026

Implementation: inc/Api/Auth.php

Base URL: /wp-json/datamachine/v1/auth

Overview

Auth endpoints manage OAuth accounts and handler authentication for social media platforms and external services.

Authentication

Requires manage_options capability. See Authentication Guide.

Handler Auth Requirements (@since v0.3.1)

Handlers can declare whether they require authentication via the requires_auth flag. When a handler’s requires_auth is false, the Auth API bypasses authentication validation for that handler, allowing handlers like public scrapers to operate without OAuth configuration.

Auth Bypass Behavior:

GET /auth/{handler_slug}/status – Returns success with requires_auth: false without checking OAuth state
PUT /auth/{handler_slug} – Returns success without requiring credentials
DELETE /auth/{handler_slug} – Returns success without disconnection operations

Provider Key Resolution

Auth endpoints accept {handler_slug} in the URL, but internally they resolve the auth provider via the handler’s auth_provider_key (from the Handlers registry). This supports shared authentication across multiple handlers (for example, one set of Meta credentials used by multiple publish destinations).

Endpoints

GET /auth/{handler_slug}/status

Check OAuth authentication status for a handler.

Permission: manage_options capability required

Parameters:

handler_slug (string, required): Handler identifier (e.g., twitter, facebook, reddit)

Returns: Authentication status, account details, and OAuth error/success states

Example Request:

curl https://example.com/wp-json/datamachine/v1/auth/twitter/status 
  -u username:application_password

Success Response – Authenticated (200 OK):

{
  "success": true,
  "data": {
    "authenticated": true,
    "account_details": {
      "username": "exampleuser",
      "id": "1234567890"
    },
    "config_status": {
      "api_key": "••••••••",
      "api_secret": "••••••••"
    },
    "handler_slug": "twitter"
  }
}

Success Response – Not Authenticated (200 OK):

{
  "success": true,
  "data": {
    "authenticated": false,
    "error": false,
    "config_status": {
      "api_key": "",
      "api_secret": ""
    },
    "handler_slug": "twitter"
  }
}

Success Response – OAuth Error (200 OK):

{
  "success": true,
  "data": {
    "authenticated": false,
    "error": true,
    "error_code": "oauth_failed",
    "error_message": "User denied authorization",
    "config_status": {
      "api_key": "",
      "api_secret": ""
    },
    "handler_slug": "twitter"
  }
}

Error Response (404 Not Found):

{
  "code": "auth_provider_not_found",
  "message": "Authentication provider not found",
  "data": {"status": 404}
}

PUT /auth/{handler_slug}

Save authentication configuration for a handler.

Permission: manage_options capability required

Parameters:

handler_slug (string, required): Handler identifier (in URL path)
Additional parameters vary by handler (e.g., api_key, api_secret, client_id, client_secret)

Storage Behavior:

OAuth providers (Twitter, Reddit, Facebook, Threads, Google Sheets): Stored to oauth_keys
Simple auth providers (Bluesky): Stored to oauth_account

Example Requests:

# Save Twitter API keys
curl -X PUT https://example.com/wp-json/datamachine/v1/auth/twitter 
  -H "Content-Type: application/json" 
  -u username:application_password 
  -d '{
    "consumer_key": "your_consumer_key",
    "consumer_secret": "your_consumer_secret"
  }'

# Save Bluesky credentials
curl -X PUT https://example.com/wp-json/datamachine/v1/auth/bluesky 
  -H "Content-Type: application/json" 
  -u username:application_password 
  -d '{
    "username": "user.bsky.social",
    "app_password": "your_app_password"
  }'

# Save Reddit OAuth keys
curl -X PUT https://example.com/wp-json/datamachine/v1/auth/reddit 
  -H "Content-Type: application/json" 
  -u username:application_password 
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

Success Response (200 OK):

{
  "success": true,
  "message": "Configuration saved successfully"
}

Success Response – No Changes (200 OK):

{
  "success": true,
  "message": "Configuration is already up to date - no changes detected"
}

Error Response (400 Bad Request):

{
  "code": "required_field_missing",
  "message": "API Key is required",
  "data": {"status": 400}
}

DELETE /auth/{handler_slug}

Disconnect an authenticated account.

Permission: manage_options capability required

Parameters:

handler_slug (string, required): Handler identifier (in URL path)

Example Request:

curl -X DELETE https://example.com/wp-json/datamachine/v1/auth/twitter 
  -u username:application_password

Success Response (200 OK):

{
  "success": true,
  "message": "Twitter account disconnected successfully"
}

Error Response (500 Internal Server Error):

{
  "code": "disconnect_failed",
  "message": "Failed to disconnect account",
  "data": {"status": 500}
}

Authentication Methods

OAuth 1.0a

Used by Twitter.

Configuration Requirements:

consumer_key – Application consumer key
consumer_secret – Application consumer secret

OAuth Flow:

Save consumer key/secret via PUT endpoint
User initiates OAuth via /datamachine-auth/twitter/ URL
Popup window handles OAuth callback
Access tokens stored automatically
Check status via GET endpoint

OAuth 2.0

Used by Reddit, Facebook, Threads, Google Sheets.

Configuration Requirements:

client_id – OAuth application client ID
client_secret – OAuth application client secret

OAuth Flow:

Save client ID/secret via PUT endpoint
User initiates OAuth via /datamachine-auth/{handler}/ URL
Popup window handles OAuth callback
Access tokens stored automatically
Check status via GET endpoint

App Password

Used by Bluesky.

Configuration Requirements:

username – Bluesky username (e.g., user.bsky.social)
app_password – Bluesky app password

Authentication Flow:

Save credentials via PUT endpoint
Credentials used directly (no OAuth flow)
Check status via GET endpoint

Supported Handlers

Twitter

Handler Slug: twitter

Auth Type: OAuth 1.0a

Configuration:

{
  "consumer_key": "your_consumer_key",
  "consumer_secret": "your_consumer_secret"
}

OAuth URL: /datamachine-auth/twitter/

Handler Slug: reddit

Auth Type: OAuth 2.0

Configuration:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

OAuth URL: /datamachine-auth/reddit/

Facebook

Handler Slug: facebook

Auth Type: OAuth 2.0

Configuration:

{
  "app_id": "your_app_id",
  "app_secret": "your_app_secret"
}

OAuth URL: /datamachine-auth/facebook/

Threads

Handler Slug: threads

Auth Type: OAuth 2.0 (uses Facebook credentials)

Configuration:

{
  "app_id": "your_app_id",
  "app_secret": "your_app_secret"
}

OAuth URL: /datamachine-auth/threads/

Google Sheets

Handler Slug: google-sheets

Auth Type: OAuth 2.0

Configuration:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

OAuth URL: /datamachine-auth/google-sheets/

Bluesky

Handler Slug: bluesky

Auth Type: App Password

Configuration:

{
  "username": "user.bsky.social",
  "app_password": "your_app_password"
}

No OAuth Flow: Credentials used directly

Integration Examples

Python Authentication Management

import requests
from requests.auth import HTTPBasicAuth

base_url = "https://example.com/wp-json/datamachine/v1/auth"
auth = HTTPBasicAuth("username", "application_password")

# Check authentication status
def check_auth_status(handler):
    url = f"{base_url}/{handler}/status"
    response = requests.get(url, auth=auth)
    return response.json()

# Save configuration
def save_auth_config(handler, config):
    url = f"{base_url}/{handler}"
    response = requests.put(url, json=config, auth=auth)
    return response.json()

# Disconnect account
def disconnect_account(handler):
    url = f"{base_url}/{handler}"
    response = requests.delete(url, auth=auth)
    return response.json()

# Usage
status = check_auth_status('twitter')
print(f"Twitter authenticated: {status['authenticated']}")

# Save Twitter config
config = {
    "consumer_key": "your_key",
    "consumer_secret": "your_secret"
}
result = save_auth_config('twitter', config)
print(f"Config saved: {result['success']}")

JavaScript OAuth Management

const axios = require('axios');

class AuthManager {
  constructor(baseURL, auth) {
    this.baseURL = `${baseURL}/auth`;
    this.auth = auth;
  }

  async checkStatus(handler) {
    const response = await axios.get(
      `${this.baseURL}/${handler}/status`,
      { auth: this.auth }
    );
    return response.data;
  }

  async saveConfig(handler, config) {
    const response = await axios.put(
      `${this.baseURL}/${handler}`,
      config,
      { auth: this.auth }
    );
    return response.data;
  }

  async disconnect(handler) {
    const response = await axios.delete(
      `${this.baseURL}/${handler}`,
      { auth: this.auth }
    );
    return response.data;
  }
}

// Usage
const authManager = new AuthManager(
  'https://example.com/wp-json/datamachine/v1',
  { username: 'admin', password: 'application_password' }
);

const status = await authManager.checkStatus('twitter');
console.log(`Authenticated: ${status.authenticated}`);

if (status.authenticated) {
  console.log(`Account: @${status.account_details.username}`);
}

Common Workflows

Setup Twitter Authentication

# 1. Save API keys
curl -X PUT https://example.com/wp-json/datamachine/v1/auth/twitter 
  -H "Content-Type: application/json" 
  -u username:application_password 
  -d '{
    "consumer_key": "your_consumer_key",
    "consumer_secret": "your_consumer_secret"
  }'

# 2. User completes OAuth at /datamachine-auth/twitter/

# 3. Check authentication status
curl https://example.com/wp-json/datamachine/v1/auth/twitter/status 
  -u username:application_password

Disconnect and Reconnect

# Disconnect account
curl -X DELETE https://example.com/wp-json/datamachine/v1/auth/twitter 
  -u username:application_password

# Reconnect via OAuth flow
# User visits /datamachine-auth/twitter/

Verify All Handler Authentication

# Check multiple handlers
for handler in twitter facebook reddit bluesky; do
  echo "Checking $handler..."
  curl -s https://example.com/wp-json/datamachine/v1/auth/$handler/status 
    -u username:application_password | jq '.authenticated'
done

chubes.net

Auth Endpoints

Overview

Authentication

Handler Auth Requirements (@since v0.3.1)

Provider Key Resolution

Endpoints

GET /auth/{handler_slug}/status

PUT /auth/{handler_slug}

DELETE /auth/{handler_slug}

Authentication Methods

OAuth 1.0a

OAuth 2.0

App Password

Supported Handlers

Twitter

Reddit

Facebook

Threads

Google Sheets

Bluesky

Integration Examples

Python Authentication Management

JavaScript OAuth Management

Common Workflows

Setup Twitter Authentication

Disconnect and Reconnect

Verify All Handler Authentication

Related Documentation

Auth Endpoints

Overview

Authentication

Handler Auth Requirements (@since v0.3.1)

Provider Key Resolution

Endpoints

GET /auth/{handler_slug}/status

PUT /auth/{handler_slug}

DELETE /auth/{handler_slug}

Authentication Methods

OAuth 1.0a

OAuth 2.0

App Password

Supported Handlers

Twitter

Reddit

Facebook

Threads

Google Sheets

Bluesky

Integration Examples

Python Authentication Management

JavaScript OAuth Management

Common Workflows

Setup Twitter Authentication

Disconnect and Reconnect

Verify All Handler Authentication

Related Documentation

More in Endpoints

Authentication

StepTypes Endpoint

Chat Sessions Endpoints