Getting Started

Base URL: https://api.redfolderresearch.com

We use token-based auth. We’ll provide you with a master token, which you use once to generate user tokens via POST /api/auth/login/. From there, all requests use that user token in the Authorization: Token <your_token> header. No OAuth flows or session management needed.

Step 1: Get a User Token

Exchange your master token for a user token. Contact your designated support person to receive your master token.

curl

curl -X POST https://api.redfolderresearch.com/api/auth/login/ \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your master token>" \
  -d '{"token_name": "My Integration"}'

Python

import requests

target_url = "https://api.redfolderresearch.com"
auth_token = "<your master token>"

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": f"Token {auth_token}"
}
response = requests.post(
    f"{target_url}/api/auth/login/",
    headers=headers,
    json={"token_name": "My Integration"},
)
user_token = response.json()["token"]

JavaScript

const targetUrl = "https://api.redfolderresearch.com";
const authToken = "<your master token>";

const response = await fetch(`${targetUrl}/api/auth/login/`, {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": `Token ${authToken}`,
  },
  body: JSON.stringify({ token_name: "My Integration" }),
});
const userToken = (await response.json()).token;

The response also includes an “expiry” field — null for these tokens (they do not expire).

Step 2: Use the User Token

Use the user token for all subsequent API requests. You do not use the master token for anything other than generating user tokens.

curl

# Verify authentication with the ping endpoint
curl https://api.redfolderresearch.com/ping_with_auth/ \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <your user token>"

Python

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": f"Token {user_token}"
}

# Verify authentication with the ping endpoint
response = requests.get(
    f"{target_url}/ping_with_auth/",
    headers=headers,
)
response.raise_for_status()
print("Authenticated successfully")

JavaScript

const headers = {
  "Accept": "application/json",
  "Content-Type": "application/json",
  "Authorization": `Token ${userToken}`,
};

// Verify authentication with the ping endpoint
const pingResponse = await fetch(`${targetUrl}/ping_with_auth/`, { headers });
if (!pingResponse.ok) throw new Error(`HTTP ${pingResponse.status}`);
console.log("Authenticated successfully");

Token Lifecycle

User tokens do not expire — they persist until explicitly revoked via POST /api/auth/logout/. Logout revokes the token used to authenticate that request, so call it with the user token you want to revoke — the master token cannot revoke user tokens. For most integrations, you generate a single token once and use it for all subsequent API calls without needing to re-authenticate.

Recommended approach for automated integrations:

1. Generate one user token during initial setup (Step 1 above)
2. Store the token securely in your system (e.g., environment variable, secrets manager)
3. Use that token for all API requests — no need to call login/logout again
4. Only regenerate if the token is compromised or you need to rotate credentials

The token_name parameter in the login request is required (the call returns 400 without it) and does not affect permissions. Case attribution uses the cc_emails field in your submission payload; when cc_emails contains no valid email, the token’s token_name is used as a fallback only if it is itself an email address — otherwise the case has no reporter attribution, so always populate cc_emails.