Authentication

The PAVE API requires authentication for all API calls, which is achieved through the use of an HMAC-SHA256 message hash as a header within the request.

Introduction

This section provides the details on how to use the curl command to access the PAVE OpenAPI sessions endpoint using API-Key, API-Token, and API-Timestamp headers. The API-Key and API-Token are used for authentication purposes, and the API-Timestamp is used for ensuring the freshness of the request.

Endpoint

https://openapi.paveapi.com/v1/sessions

HMAC-SHA256

HMAC (Keyed-Hash Message Authentication Code) is a cryptographic technique that calculates a message authentication code by combining a cryptographic hash function with a secret key. In the case of the PAVE Capture API, the cryptographic hash function used is SHA256, resulting in the algorithm known as HMAC-SHA256.

Prerequisites

A valid API Key and API Token should be obtained before accessing the API endpoint.
curl must be installed on your system.

Steps to Use curl

Open a terminal or command prompt.
Use the following curl command to access the API endpoint:

curl -H "API-Key: <Your_API_Key>" \
     -H "API-Token: <Your_Generated_Access_Token>" \
     -H "API-Timestamp: <UTC_Datetime_String>" \
     https://openapi.paveapi.com/v1/sessions

Replace <Your_API_Key> with your API Key.
Replace <Your_Generated_Access_Token> with your API Token.
Replace <UTC_Datetime_String> with the UTC datetime in the format YYYY-MM-DDTHH:MM:SSZ. For example, 2023-02-11T12:00:00Z.
Execute the curl command.
The API endpoint will return a JSON object containing the session data.

Headers

The following headers are required for each API request:

Header Name

Description

API-Key

Your API Key, which is used to identify your account and provide access to the API.

API-Token

A generated access token, which is used to authenticate your API request.

API-Timestamp

The UTC datetime string, which is used to verify the freshness of your request.

Note

Make sure to replace the placeholders with the actual values before executing the curl command.
Ensure that the UTC datetime string in the API-Timestamp header is accurate and up-to-date, as it is used for ensuring the freshness of the request.
API-Token: will expire within 5 minutes.

Response

If the request is successful, the API server will return a JSON object that contains the session information, including the session ID, expiration time, and the associated API Key and access token.

Example response:

{
  "session_id": "f8f4e4c1-6416-4d4a-8b16-f15a4e4a1c2d",
  "expiration": "2023-02-11T12:00:00Z",
  "api_key": "abcd1234",
  "api_token": "efgh5678"
}

Error Responses

If there is an error with the request, the API server will return a JSON object with an error message. Some possible error messages include:

Invalid API Key: The provided API Key is invalid or does not match any existing accounts.
Invalid API Token: The provided access token is invalid or has expired.
Invalid API Timestamp: The provided UTC datetime string is invalid or the request is stale.

Example error response: 403 Forbidden

 {
  "message": "Unable to validate the request, please recheck your API-Key and API-Token."
}

Here are examples of how to make this API request using different programming languages:

JavaScript

const axios = require('axios');

const apiKey = '<Your_API_Key>';
const apiToken = '<Your_Generated_Access_Token>';
const apiTimestamp = '<UTC_Datetime_String>';

axios({
  method: 'post',
  url: 'https://openapi.paveapi.com/v1/sessions',
  headers: {
    'API-Key': apiKey,
    'API-Token': apiToken,
    'API-Timestamp': apiTimestamp
  }
})
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error.response.data);
  });

Python

import requests

api_key = '<Your_API_Key>'
api_token = '<Your_Generated_Access_Token>'
api_timestamp = '<UTC_Datetime_String>'

headers = {
    'API-Key': api_key,
    'API-Token': api_token,
    'API-Timestamp': api_timestamp
}

response = requests.post(
    'https://openapi.paveapi.com/v1/sessions',
    headers=headers
)

if response.status_code == 200:
    print(response.json())
else:
    print(response.json()['error'])

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

const apiKey = "<Your_API_Key>"
const apiToken = "<Your_Generated_Access_Token>"
const apiTimestamp = "<UTC_Datetime_String>"

func main() {
	url := "https://openapi.paveapi.com/v1/sessions"

	client := &http.Client{}
	req, err := http.NewRequest("POST", url, nil)
	if err != nil {
		fmt.Println(err)
		return
	}

	req.Header.Set("API-Key", apiKey)
	req.Header.Set("API-Token", apiToken)
	req.Header.Set("API-Timestamp", apiTimestamp)

	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}

	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)

	fmt.Println(result)
}

Swift

import Foundation

let apiKey = "your_api_key"
let apiToken = "your_generated_access_token"
let url = URL(string: "https://openapi.paveapi.com/v1/sessions")!
let timestamp = DateFormatter().string(from: Date())

var request = URLRequest(url: url)
request.addValue(apiKey, forHTTPHeaderField: "API-Key")
request.addValue(apiToken, forHTTPHeaderField: "API-Token")
request.addValue(timestamp, forHTTPHeaderField: "API-Timestamp")

let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
    guard let data = data, let response = response as? HTTPURLResponse, error == nil else {
        print("Error: \(error?.localizedDescription ?? "Unknown error")")
        return
    }

    if response.statusCode == 200 {
        print(String(data: data, encoding: .utf8) ?? "Empty response")
    } else {
        print("Unexpected response code: \(response.statusCode)")
        print(String(data: data, encoding: .utf8) ?? "Empty response")
    }
}
task.resume()

Kotlin

import java.net.URL
import javax.net.ssl.HttpsURLConnection

fun main() {
    val apiKey = "<Your_API_Key>"
    val apiToken = "<Your_Generated_Access_Token>"
    val apiTimestamp = "<UTC_Datetime_String>"

    val url = URL("https://openapi.paveapi.com/v1/sessions")

    with(url.openConnection() as HttpsURLConnection) {
        requestMethod = "POST"
        setRequestProperty("API-Key", apiKey)
        setRequestProperty("API-Token", apiToken)
        setRequestProperty("API-Timestamp", apiTimestamp)

        inputStream.bufferedReader().use {
            val response = it.readText()
            println(response)
        }
    }
}

PreviousDeveloper Docs NextGenerate Access Token

Last updated 2 years ago