> For the complete documentation index, see [llms.txt](https://motorweb.gitbook.io/motorweb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://motorweb.gitbook.io/motorweb/motorweb-reports/authentication.md).

# Authentication

Authenticating with the MotorWeb NZ B2B API.

MotorWeb NZ uses **mutual TLS (mTLS)** for the B2B API. You present a MotorWeb-issued client certificate on every request. There is no API key, no bearer token and no password on these endpoints.

## How mTLS works

A digital handshake with verification in both directions.

1. **You prove who you are.** Your system presents a client certificate. This is your digital ID card.
2. **We prove who we are.** Our API presents its own certificate, so you know you are talking to MotorWeb.
3. **The connection is encrypted.** Once both sides verify each other, all traffic between your system and ours is private.

MotorWeb operates its own certificate authority and issues your certificate directly. Contact your account manager to request one.

## Environments

<table><thead><tr><th width="214" align="center">Environment</th><th>Base URL</th></tr></thead><tbody><tr><td align="center">UAT</td><td><code>https://robot.uat.motorweb.co.nz</code></td></tr><tr><td align="center">Production</td><td><code>https://robot.motorweb.co.nz</code></td></tr></tbody></table>

{% hint style="warning" %}
**Each environment needs its own certificate.**

A UAT certificate does not authenticate against Production, and a Production certificate does not authenticate against UAT. Request both from your account manager before you start work.
{% endhint %}

## Certificate expiry

Certificates expire. MotorWeb emails a warning **60 days** before expiry to the contact on the account.

Do not wait for the warning to reach your inbox. Record the expiry date when you install a certificate, and set your own reminder. An expired certificate returns `401` on every request with no other explanation.

## Using your certificate

### cURL

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

### Postman

1. Open **Settings**.
2. Under **General**, turn **SSL certificate verification** off.
3. Under **Certificates**, select **Client Certificates**, then **Add Certificate**.
4. Set **Host** to `robot.motorweb.co.nz`.
5. Select your `.p12` file as the **PFX file**.
6. Enter the certificate password as the **Passphrase**.

You can now call any endpoint on that host. Repeat the steps with host `robot.uat.motorweb.co.nz` for UAT.

## Privileges

Your certificate identifies your account. Your account's privileges then decide which reports you can run.

A valid certificate with the wrong privilege returns `400` with `MotorWeb-Error-Code: BAD-ACCOUNT`, not `403`. Each report page lists the privilege it needs. Contact your account manager to have one enabled.

## Acting on behalf of another user

Two optional parameters let a parent account transact on behalf of a child account. Both are applied **after** certificate authentication, so the certificate is still required.

<table><thead><tr><th width="180">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>accountId</code></td><td>The MotorWeb user ID to transact as. Your account must hold the privilege to specify a user ID.</td></tr><tr><td><code>oAuthToken</code></td><td>An OAuth access token identifying an end user under your account. See <a href="/motorweb/motorweb-reports/oauth-access-tokens.md">OAuth Access Tokens</a>.</td></tr></tbody></table>

## Authentication errors

<table><thead><tr><th width="80">HTTP</th><th width="170">Error code header</th><th>Cause</th></tr></thead><tbody><tr><td>401</td><td>—</td><td>No certificate presented, the certificate expired, or it does not match an account in this environment.</td></tr><tr><td>400</td><td><code>BAD-ACCOUNT</code></td><td>The certificate is valid but your account cannot run this report, or a transaction limit was reached.</td></tr></tbody></table>

**Notes:**

* The client certificate is the only credential on `/b2b/` and `/action/robot` endpoints
* Certificates are environment specific
* Store the `.p12` file and its password securely. Anyone holding both can transact as your account
* Set your own expiry reminder rather than relying on the 60-day email