Authentication

All requests to the Robohead API must be authenticated using one of your private, per-user API keys. Refer to Creating & Managing your API Keys in the official RoboHead documentation.

Authentication is performed by passing your API key as an HTTP header: X-API-Key.

Generating & Storing Your API Key

Both users and account administrators can generate API keys. When you generate a new key, you must copy and save it in a secure location immediately.

For security, we hash all API keys in our database and have no mechanism to retrieve a lost key. If you lose your key, you will need to revoke the old one and generate a new one.

⚠️ Important: Authentication Method Update

We have recently updated our authentication method to improve security.

Previously, API keys were accepted as a query parameter (e.g., ?userApiToken=...). This method is now deprecated and will be fully discontinued on July 1, 2026.

Please update your code to use the X-API-Key HTTP header as shown in the examples below.

Sample Usage & Migration Examples

In the examples below we show a typical API call to get the user's list of active projects. Replace ACCOUNT_URL with your company's unique Robohead URL (e.g., mycompany.robohead.com). The endpoint (e.g., project.do) and command (e.g. cmd=ListActiveProject) should be replaced with the specific API endpoint and command, respectively, you are calling (such as user.do?cmd=GetUser, task.do?cmd=AddTask, etc.).

cURL

New & Correct Method (using -H header):

# CORRECT
curl "https://ACCOUNT_URL.robohead.com/project.do?cmd=ListActiveProject" \
  -H "X-API-Key: YOUR_API_KEY"

Old & Deprecated Method (using ? query parameter):

# DEPRECATED - Please update
curl "https://ACCOUNT_URL.robohead.com/project.do?userApiToken=YOUR_API_KEY&cmd=ListActiveProject"

Python (with requests library)

New & Correct Method (using headers dict):

# CORRECT
import requests

api_key = "YOUR_API_KEY"
cmd = "ListActiveProject"
url = "https://ACCOUNT_URL.robohead.com/project.do"

headers = {
    "X-API-Key": api_key
}

params = {
    "cmd": cmd
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Old & Deprecated Method (using params dict):

# DEPRECATED - Please update
import requests

api_key = "YOUR_API_KEY"
cmd = "ListActiveProject"
url = "https://ACCOUNT_URL.robohead.com/project.do"

params = {
    "userApiToken": api_key,
    "cmd": cmd
}

response = requests.get(url, params=params)
print(response.json())

JavaScript (with fetch)

New & Correct Method (using headers object):

// CORRECT
const url = "https://ACCOUNT_URL.robohead.com/project.do?cmd=ListActiveProject";
const apiKey = "YOUR_API_KEY";

fetch(url, {
  method: "GET",
  headers: {
    "X-API-Key": apiKey,
    "Content-Type": "application/json"
  }
})
.then(response => response.json())
.then(data => console.log(data));

Old & Deprecated Method (using query string):

// DEPRECATED - Please update
const url = "https://ACCOUNT_URL.robohead.com/project.do?userApiToken=YOUR_API_KEY&cmd=ListActiveProject";

fetch(url)
  .then(response => response.json())
  .then(data => console.log(data));

Error Responses

If your API key is missing or invalid, the API will return a 401 Unauthorized status code.

{
    "returnCode": 1,
    "browser": "PostmanRuntime/7.49.0",
    "sessionId": "4CFF4DB6EDBDBCDF8DD5B5B94D8B0E98-0001",
    "errorMessages": [
        {
            "messageKey": "msg_error_invalidToken",
            "detailedMessage": "Token key is invalid for performing operation."
        }
    ],
    "success": false
}