Getting Started with the TCAP API

Get started using the Tech Against Terrorism TCAP API. This document outlines how you can obtain an authentication token and use our API services.

Authentication

To use the TCAP API services, you need to obtain an access token using the credentials provided during on-boarding.

Setting Up Credentials

Create an .env file in your project directory and add your credentials:

TCAP_URL=https://beta.terrorismanalytics.org/token-auth/tcap/
TCAP_USERNAME={YOUR_TCAP_USERNAME}
TCAP_PASSWORD={YOUR_TCAP_PASSWORD}

IMPORTANT: Do not share your username or password with anyone or hardcode them in your code base. Store them securely as environment variables.

Obtaining an Access Token

To obtain a token make a request to the TCAP authentication endpoint:

POST https://beta.terrorismanalytics.org/token-auth/tcap/
{
  username: YOUR_TCAP_USERNAME
  password: YOUR_TCAP_PASSWORD
}
200 OK
{
  {
    "token": "accessToken",
    "user": {
        "id": 1,
        "username": "",
        "first_name": "",
        "last_name": "",
        "email": "",
        "organisation": "",
        "permissions": [...],
        "job_title": "",
        "terms": "",
        "terms_archive": "",
        "email_verified": true
    }
}

Python Example

import requests
import json
import os

def get_access_token() -> str | None:
    url = os.getenv("TCAP_URL")
    credentials = {
        "username": os.getenv("TCAP_USERNAME"),
        "password": os.getenv("TCAP_PASSWORD"),
    }
    response = requests.post(url, 
       headers={'Content-Type': 'application/json'}
       data=json.dumps(credentials), 
    )

    if response.status_code == 200:
        return response.json().get('token')
    else:
        return None

TypeScript Example

async function getAccessToken(): Promise<string | null> {
    const url = process.env.TCAP_URL;
    const credentials = {
        username: process.env.TCAP_USERNAME,
        password: process.env.TCAP_PASSWORD,
    };

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(credentials)
        });

        if (response.ok) {
            const data = await response.json();
            return data.token;
        } else {
            return null;
        }
    } catch (error) {
        console.error(error);
        return null;
    }
}

IMPORTANT: Keep the token returned from a successful login in a secure location and do not share it with anyone.

Token Expiry and Re-authentication

The TCAP JWT access token expires after 2 hours. You need to re-authenticate when it expires. If you're integrating this into an automated system, obtain a new token before making a request.

Example Implementation

Python Example

import requests
import json
import os

def get_access_token() -> str | None:
    url = os.getenv("TCAP_URL")
    credentials = {
        "username": os.getenv("TCAP_USERNAME"),
        "password": os.getenv("TCAP_PASSWORD"),
    }
    response = requests.post(url, 
       headers={'Content-Type': 'application/json'}
       data=json.dumps(credentials), 
    )

    if response.status_code == 200:
        return response.json().get('token')
    else:
        return None

# execute_task being some task you have created using our services 

def execute_task(token: str, task_url: str) -> None | Response:
    headers = {'Authorization': f'Bearer {token}'}
    response = requests.get(task_url, headers=headers)

    if response.status_code == 401:  

        # Token expired, get a new one

        token = get_access_token()
        headers = {'Authorization': f'Bearer {token}'}

        # Invoke your task

        response = requests.get(task_url, headers=headers)

    if response.status_code == 200:
        return response.json()
    else:
        return None

TypeScript Example

async function getAccessToken(): Promise<string | null> {
    const url = process.env.TCAP_URL;
    const credentials = {
        username: process.env.TCAP_USERNAME,
        password: process.env.TCAP_PASSWORD,
    };

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(credentials)
        });

        if (response.ok) {
            const data = await response.json();
            return data.token;
        } else {
            return null;
        }
    } catch (error) {
        console.error(error);
        return null;
    }
}

// execute task being some task you have created using our services 
async function executeTask(taskUrl: string): Promise<any | null> {
    let token = await getAccessToken();
    let headers = {'Authorization': `Bearer ${token}`};
    let response = await fetch(taskUrl, {headers: headers});

    if (response.status === 401) {  

        // Token expired, get a new one

        token = await getAccessToken();
        headers = {'Authorization': `Bearer ${token}`};
        
        // Execute your task

        response = await fetch(taskUrl, {headers: headers});
    }

    if (response.status === 200) {
        return response.json();
    } else {
        return null;
    }
}

IMPORTANT: Failure to authenticate 10 consecutive times will result in your account being blocked. Contact [email protected]

If you wish to use our API services please make a request through this form