Users and authentication

Authentication

You need to call the POST /keys endpoint to create a pair of keys. The endpoint needs you to use HTTP Basic authentication using your Teamscope email and password.

Below is an example of a typical response from that endpoint.

JSON

{
    "type": "other",
    "creation": "2021-08-25T15:20:12.969Z",
    "expiration": "2021-09-22T15:20:12.969Z",
    "data": "99de3ec8f979c0c4a22145e8c6b3284cdc27e7445872bd2a2b26aed1c2b2323a",
    "user": "/user/a636261421aaa5bc",
    "unscrambledUser": "/api/user/017a81587ceea5bc",
    "uri": "/key/9a5916c354879a581a3615cc3e9a99da",
    "requiresOnboarding": false,
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoib3RoZXIiLCJjcmVhdGlvbiI6IjIwMjEtMDgtMjVUMTU6MjA6MTIuOTY5WiIsImV4cGlyYXRpb24iOiIyMDIxLTA5LTIyVDE1OjIwOjEyLjk2OVoiLCJkYXRhIjoiOTlkZTNlYzhmOTc5YzBjNGEyMjE0NWU4YzZiMzI4NGNkYzI3ZTc0NDU4NzJiZDJhMmIyNmFlZDFjMmIyMzIzNyIsInVzZXIiOiIvdXNlci9hNjM2MjYxNDIxYWFhNWJjIiwidW5zY3JhbWJsZWRVc2VyIjoiL2FwaS91c2VyLzAxN2E4MTU4N2NlZWE1YmMiLCJ1cmkiOiIva2V5LzlhNTkxNmMzNTQ4NzlhNTgxYTM2MTVjYzNlOWE5OWRlIiwicmVxdWlyZXNPbmJvYXJkaW5nIjpmYWxzZSwiaWF0IjoxNjI5OTA0ODE0LCJleHAiOjE2Mjk5MDY2MTR9.lsCIjAGDFGwABrhZzAHWjQajSgil2ohC87D7miQ-w2A"
}

In the previous payload, the key identifier would be 9a5916c354879a581a3615cc3e9a99da and the key data would be 99de3ec8f979c0c4a22145e8c6b3284cdc27e7445872bd2a2b26aed1c2b2323a.

Requests Signing

Teamscope uses the HTTP Signature authentication scheme to secure its endpoints.

Below you will find below a snippet of code that signs an HTTP request.

JavaScript

// HTTP Signature scheme script that can be used
// in Postman to sign HTTP requests

const moment = require("moment");
const CryptoJS = require("crypto-js");

const method = pm.request.method; // e.g. "GET"
const requestUrl = pm.request.url.getPathWithQuery(); // e.g "/investigation/:id/responses"

const hexKeyUri = pm.collectionVariables.get("keyUri"); // hexadecimal key identifier
const hexKeyData = pm.collectionVariables.get("keyData"); // hexadecimal private key

const keyUri = CryptoJS.enc.Hex.parse(hexKeyUri);
const keyData = CryptoJS.enc.Hex.parse(hexKeyData);
const b64KeyUri = CryptoJS.enc.Base64.stringify(keyUri);

const date = moment().utc().format("ddd, D MMM YYYY HH:mm:ss [GMT]");
const message = method + " " + requestUrl + " HTTP/1.1\ndate: " + date

const hash = CryptoJS.HmacSHA256(message, keyData);
const b64Hash = CryptoJS.enc.Base64.stringify(hash);
const headerValue = "Signature keyId=\"" + b64KeyUri + "\",algorithm=\"hmac-sha256\",headers=\"request-line date\",signature=\"" + b64Hash + "\"";

pm.request.headers.add({ // Requests need to include an X-Date header
    key: "X-Date",
    value: date,
});
pm.request.headers.add({ // The "Authorization" header signs the request
    key: "Authorization",
    value: headerValue,
});