Skip to content

Register for API access

To access the Datarock API, you will need to generate a keypair. This process involves creating a public-private key pair, where the private key remains securely stored on your server, and the public key is registered with Datarock. Each API request you make will be authenticated and verified using this public key, ensuring the authenticity and security of your requests.

Note

Only managers and administrators have permissions that enable registration for API access.

Generating a keypair

Note

You are free to generate your keypair using any method you like, these instructions are provided as a guide only.

  1. Open a terminal window.

  2. Generate a new RSA private key by running the following command: 

    openssl genrsa -out private_key.pem 2048

  3. You will now have a private key saved in the file private_key.pem.

  4. To generate the corresponding public key, run the following command: 

    openssl rsa -in private_key.pem -pubout -out public_key.pem

  5. The public key will be saved in the file public_key.pem.

Note: The instructions provided here are general, but there may be slight variations depending on the specific versions of OpenSSL you have installed.

Registering your public key with Datarock's API

Note

Only one keypair can be registered per account at the same time. If you register a new keypair, the old one will be invalidated.

Using the UI

To register your public key with Datarock's API using the UI, first confirm with the Datarock Support Team that you have the necessary permissions for API access. Once confirmed, follow these instructions:

  1. Log in to the Datarock platform UI
  2. Connect with the account that will own the keypair.
  3. Use the Navigation Menu > API Key.
  4. Upload your public key file.
  5. Click the Register button.

public key modal screenshot

Generating the request signature

The Signature header should be a signed JWT with a payload in this format:

{
  iat: number,
  requestHash: string
}

iat

iat is a standard JWT claim, and should be the time (in seconds from Unix epoch) that the token was issued. It must not be more than 5 minutes old, or more than 1 minute into the future.

requestHash

The requestHash is a SHA512 hash created by combining the requestor's email address, the iat claim, and the request URL, separated by slashes.

For example, if this request was being made on behalf of testuser@datarock.com.au on 20th March 2023 at 5:00pm to URL https://mine.datarock.com.au/some-api?projectUuid=0ccf3042-de5e-41b5-b344-e1366916d06f, then:

  • The value to hash would be testuser@datarock.com.au/1679292000/https://mine.datarock.com.au/some-api?projectUuid=0ccf3042-de5e-41b5-b344-e1366916d06f
  • The computed hash would be 54e387bb0db4cc441d720b044d0a904626821e972545e50fdbe9eb646c1dcb87a2e8a8f7b4455999e8243dd879c1eca1cfdc7c2ed6b015f7380f26bf4a062493

When including multiple query string parameters, make sure to order them alphabetically by parameter name. For example, limit=500&offset=0 is valid, while offset=0&limit=500 is not. If the query string parameters are not correctly ordered, the request hash will not match, and authorization will be denied.

Example implementations

The below examples provide functions that return the headers you would need to include when interacting with APIs protected by the public API authoriser.

NodeJS

This example depends on:

import { createHash } from "crypto";
import { sign } from "jsonwebtoken";

function generateRequestHeaders(
  privateKey: string | Buffer,
  requestUrl: string,
  userEmail: string,
  issuedTime: Date = new Date()
) {
  const iat = Math.floor(issuedTime.getTime() / 1000);
  const requestStringToHash = `${userEmail}/${iat}/${requestUrl}`;
  const jwtPayload = {
    requestHash: createHash("sha512").update(requestStringToHash).digest("hex"),
    iat,
  };

  return {
    signature: sign(jwtPayload, privateKey, { algorithm: "RS256" }),
    "x-api-user": userEmail,
  };
}

Python

This example depends on the following libraries:

import jwt
import datetime
import hashlib

def generate_request_headers(private_key, request_url, user_email, issued_time = None): 
    issued_time = datetime.datetime.now(tz=datetime.timezone.utc) if issued_time is None
    iat = int(issued_time.timestamp())
    request_str_to_hash = f'{user_email}/{iat}/{request_url}'.encode('utf-8')
    jwt_payload = {
        "requestHash": hashlib.sha512(request_str_to_hash).hexdigest(),
        "iat": iat
    }

    return {
        "signature": jwt.encode(jwt_payload, private_key, algorithm="RS256"),
        "x-api-user": user_email
    }