Authentication

Authenticating with MotorWeb NZ API's

Certificate Based Authentication (mTLS)

At MotorWeb NZ, we use a secure method called mTLS (mutual Transport Layer Security) for authenticating access to our APIs. This is done through the use of certificates which must be passed with each API request.

A Quick Summary of mTLS:

Think of it like a digital handshake with two-way verification, in basic terms it works like this:

• You Prove You're You: When your system connects to our API, it presents a unique digital certificate. This certificate acts like your "digital ID card", proving your identity to us.

• We Prove We're Us: At the same time, our API also presents its own digital certificate to your system. This confirms that you are indeed connecting to the legitimate MotorWeb API and not a fraudulent site.

• Secure, Encrypted Connection: Once both sides have successfully verified each other's certificates, a secure, encrypted communication channel is established. All data exchanged between your system and our API is then encrypted and private.

Real World Examples:

Using cURL:

Below is an example on how to include a certificate and password in your cURL request:

curl --cert-type P12 --cert motorwebnz.p12:<CERTPASSWORD> https://robot.motorweb.co.nz/b2b/bvi/generate/4.0?plateOrVin=ABC123

Using Postman

In the Postman application, head to the settings and do the following:

• General > SSL certificate verification > OFF

• Certificates > Client Certificates > Add Certificate >

  • Host = robot.motorweb.co.nz

  • PFX file = select locally saved MotorWeb certificate (e.g. motorweb.p12)

  • Passphrase = Password for certificate (check emails)

Once these steps have been complete you should be able to make a request to any of our API's with the base URL of robot.motorweb.co.nz

Using Java

import org.w3c.dom.Document;
 
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.dom.DOMSource;
import java.net.URL;
 
/**
 * Demonstration of connecting to the MotorWeb robot 
 * 
 * Takes in two program parameters being the path to the motorweb.p12 file (should have been emailed to you) and the 
 * password to access that file. 
 * 
 * The javax.net.ssl.* properties are normally specified as VM parameters on the command line used to run java but are kept 
 * internally here to keep this to a single file demonstration. 
 * 
 */
 
public class RobotDemo
{ 
    public static void main( String[] args )
    { 
        if ( args.length == 2 ) {
            // These are the properties that specify the key store of client certificate(s)
            System.setProperty( "javax.net.ssl.keyStore", args[0] );  // The path to the .p12 file
            System.setProperty( "javax.net.ssl.keyStorePassword", args[1] );  // The password of the p12 file
            System.setProperty( "javax.net.ssl.keyStoreType", "pkcs12" );  // Default is JKS, we're using PKCS12
            try {
                // URL is taken from the https://www.motorweb.co.nz/action/robotSpecs page
                URL url = new URL( "https://robot.motorweb.co.nz/action/robotLoadVir/4.0?reference=43888db2" );
                // Parse the XML into a DOM tree
                Document document = DocumentBuilderFactory.newInstance().newDocumentBuilder().parse( url.openStream() ); 
                // Serialize it out to the console
                TransformerFactory.newInstance().newTransformer().transform( new DOMSource( document ), new StreamResult( System.out ) );
            } catch ( Exception e ) {
                e.printStackTrace(); 
            } 
        } else {
            System.err.println( "Need arguments:  /path/to/motorweb.p12  password" ); 
        } 
    } 
}