Authentication

Verifying user identity and securing API access to Voodoo Robotics services.

Overview

Authentication is how the API checks that a request is really coming from you. You send credentials such as an API key or login session with the request, and the server uses that information to decide whether to allow access. Voodoo supports four authentication methods:

Basic Authentication — Disabled by default. Simple but insecure over HTTP. Available over HTTPS by request only.
API-KEY Authentication — Each API User account gets its own key. Simple and effective.
Session-based Authentication — Secure and convenient. Uses a session cookie with CSRF token and Referer header.
OAuth2 — Industry-standard protocol supported by libraries in many programming languages.

Basic Authentication

Not Recommended

By default, Voodoo servers do not allow Basic Authentication. Using Basic Authentication over HTTP is completely insecure. Voodoo can enable it on a self-hosted Big Block by request only for HTTPS connections.

The advantage of Basic Authentication is that individual POST messages can be made without maintaining any state between requests. There is no login step required.

import requests

baseURL = "https://www.voodoodevices.com/"  # or your self-hosted Big Block
apiURL = baseURL + "api/"
deviceEndpoint = apiURL + "device/"
deviceID = "CCCCCC:DDDDDD"

username = "yourusername"
password = "yourpassword"

session = requests.Session()
session.post(
    deviceEndpoint + deviceID + "/",
    auth=(username, password),
    json={
        'command': 'flash',
        'line1': 'Hello',
        'line2': 'There',
    }
)

API-KEY Authentication

API key authentication ensures requests are from an authorized source. A unique key is issued to each API user account and included in the API-KEY header. When a request is received, the server checks the key against authorized keys and grants access if valid.

Protect Your Key

Treat your API key like a password. Never expose it in client-side code or public repositories.

import requests

baseURL = "https://www.voodoodevices.com/"  # or your self-hosted Big Block
apiURL = baseURL + "api/"
deviceEndpoint = apiURL + "device/"
deviceID = "CCCCCC:DDDDDD"

API_KEY = "your-api-key"  # obtained from API User Account

session = requests.Session()
session.post(
    deviceEndpoint + deviceID + "/",
    headers={'API-KEY': API_KEY},
    json={
        'command': 'flash',
        'line1': 'Hello',
        'line2': 'There',
    }
)

Session-based Authentication

Session-based authentication is secure and conveniently simple. When a client logs into a server, it obtains both a session ID (in the cookie header) and a CSRF token.

Headers Required

POST requests require two additional headers:

referer — Set to the base URL
x-csrf-token — The CSRF token from the login response

GET requests can be made without these header additions.

import requests
import json

baseURL = "https://www.voodoodevices.com/"  # or your self-hosted Big Block
apiURL = baseURL + "api/"
deviceEndpoint = apiURL + "device/"
deviceID = "CCCCCC:DDDDDD"

username = "yourusername"
password = "yourpassword"

session = requests.Session()

# Step 1: Login to obtain session cookie and CSRF token
x = session.post(
    apiURL + "user/login/",
    json={
        'username': username,
        'password': password
    }
)
z = json.loads(x.text)

# Step 2: Use the CSRF token and referer in subsequent requests
session.post(
    deviceEndpoint + deviceID + "/",
    headers={
        'referer': baseURL,
        'x-csrf-token': z['token'],
    },
    json={
        'command': 'flash',
        'line1': 'Hello',
        'line2': 'There',
    }
)

Python Session Handling

Python's requests.Session() object automatically stores and sends the session cookie on subsequent requests. Other languages may require you to manage cookies manually.

OAuth2

OAuth2 is an industry-standard protocol for authentication. Voodoo supports it with two approaches: manual token management and automatic token refresh using libraries.

OAuth2 — Manual Token Management

This approach shows exactly how to obtain a Bearer Token from Big Block and use it for POST access.

Token Request Format

The first POST request to obtain the token passes parameters as x-www-form-urlencoded data (not JSON). Use the data parameter in Python, not json.

The server responds with:

Token Response

{
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "read write",
  "refresh_token": "yyyyyyyyyyyyyyyyyyyyyyyy"
}

import requests
import json

baseURL = "https://www.voodoodevices.com/"  # or your self-hosted Big Block
apiURL = baseURL + "api/"
tokenURL = baseURL + "oauth2/token/"
deviceEndpoint = apiURL + "device/"
deviceID = "CCCCCC:DDDDDD"

username = "yourusername"
password = "yourpassword"
client_id = "xxxxget_this_client_id_from_usxxxxxxx"

session = requests.Session()

# Step 1: Request token (note: use 'data', not 'json')
x = session.post(
    tokenURL,
    data={
        'grant_type': 'password',
        'username': username,
        'password': password,
        'client_id': client_id,
    }
)
z = json.loads(x.text)

# Step 2: Use Bearer token for API calls
session.post(
    deviceEndpoint + deviceID + "/",
    headers={
        'Authorization': z['token_type'] + " " + z['access_token'],
    },
    json={
        'command': 'flash',
        'line1': 'Hello',
        'line2': 'There',
    }
)

OAuth2 — Automatic Token Refresh

Python's requests_oauthlib and oauthlib libraries simplify OAuth2 by handling token renewal automatically. You never have to worry about token expiry.

Recommended for Python

If your client software is written in Python, this is the recommended authentication approach for production use. Other languages have similar OAuth2 libraries — contact Voodoo support for recommendations.

OAuth2 with Auto-Refresh (Python)

from oauthlib.oauth2 import LegacyApplicationClient
from requests_oauthlib import OAuth2Session

baseURL = "https://www.voodoodevices.com/"  # or your self-hosted Big Block
apiURL = baseURL + "api/"
tokenURL = baseURL + "oauth2/token/"
deviceEndpoint = apiURL + "device/"
deviceID = "CCCCCC:DDDDDD"

username = "yourusername"
password = "yourpassword"
client_id = "xxxxget_this_client_id_from_usxxxxxxx"

session = OAuth2Session(
    client=LegacyApplicationClient(client_id=client_id),
    auto_refresh_url=tokenURL,
    auto_refresh_kwargs={
        "client_id": client_id,
        "username": username,
        "password": password,
    },
    token_updater=lambda t: t,
)

session.fetch_token(
    token_url=tokenURL,
    username=username,
    password=password,
    include_client_id=True,
)

# Token refresh is handled automatically
session.post(
    deviceEndpoint + deviceID + "/",
    json={
        'command': 'flash',
        'line1': 'Hello',
        'line2': 'There',
    }
)

Security Notes

✓

Always use HTTPS for all API communications in production.

✓

Store API keys and credentials securely — never in source code or public repositories.

✓

Use OAuth2 with automatic token refresh for long-running production integrations.

✓

Rotate API keys periodically and revoke keys that are no longer in use.

✗

Avoid Basic Authentication over HTTP — it transmits credentials in the clear.

Method Comparison

Method	Complexity	Security	Best For
Basic Auth	Low	Low	Quick tests (HTTPS only)
API-KEY	Low	Medium	Server-to-server integrations
Session + CSRF	Medium	High	Interactive applications
OAuth2	Higher	High	Production integrations

REST API Overview

Explore available API endpoints and usage patterns

Getting Started

Set up your first integration with Voodoo Robotics

Server & Deployment

Choose your server deployment option

Best Practices

Deployment tips and operational guardrails