1. API Docs

    🔒 API Key Security

    Your API key is the only thing that stands between the CarJam APIs and a request charged to you. Anyone who has it can make calls as you, and they are billed to your Development Connection. The monthly cap limits how much a leaked key, or a bug in your own code, can cost you before you notice.

    Your API key is a password

    CarJam does not ask who is holding the key: a request that carries a valid key is treated as yours. Anyone who has your key can:

    • Spend your money. Every request is charged at your prices to your Development Connection. With account charging on, your card is topped up automatically as the balance runs low, so a leaked key keeps being paid for until the cap stops it.
    • Read vehicle and owner data in your name. Owner names, addresses, money owing and the other personal information the APIs return is fetched under your connection, and you remain responsible for it under our terms and conditions and the Privacy Act 2020.
    • Use up your allowance. Their requests count against your throttling limit and your cap, so your own integration can be throttled or stopped by someone else's traffic.

    The key is sent in the query string (?key=<api-key>), so it is written to every server log, proxy log and browser history the request passes through. It is easy to leak without meaning to.

    How keys get exposed

    • Calling the API from a web page, browser extension or mobile app. Anything shipped to your users' devices can be read by them.
    • Committing the key to a source repository, especially a public one, or leaving it in a sample, Postman collection or .env file that is shared.
    • Pasting a full request URL into a support ticket, chat, forum post, screenshot or error report.
    • Logging full request URLs in your own application or analytics.
    • Storing it in an AI agent or MCP integration configuration that other people can open.
    • A staff member who leaves while still holding the key.

    Keeping your key safe

    • Call CarJam only from your server. Keep the key in server-side configuration or a secrets store, and have your own front end call your server.
    • Restrict it to your IP addresses. Under Allowed IPs on the Developer page, list the addresses your servers call from. A request with your key from any other address is refused, so a leaked key is useless to anyone else.
    • Rotate a key you suspect. Under API Keys, generate a new key, move your integration onto it, then disable the old one. A disabled key is refused straight away.
    • Watch your usage. The API Log and API Usage show every request made with your keys. Requests you do not recognise mean your key is in someone else's hands.
    • Keep the cap on, set to what you expect to spend in a month (see below).
    • Keep your alert addresses current, so the cap warnings reach someone who will act on them.

    If you think your key has been exposed, disable it, generate a new one and contact us so we can look at the requests made with it.

    The monthly cap

    Every Development Connection on production starts with a cap on what its API requests may cost in a calendar month. A new connection's cap is NZ$20.00. The test environment has no cap: its data is free.

    Why there is a cap

    • It limits the damage from a leaked key. Whoever is using your key can spend no more than about the cap before every request is refused.
    • It catches runaway code. A retry loop with no pause, a job that replays the same list again and again, or a deploy that calls the API on every page view can spend a month's budget in an hour. The cap turns that into an error you notice, not an invoice you did not expect.
    • It keeps spending predictable. Usage is invoiced, or charged to your account, after the requests are made. The cap is a ceiling you choose in advance.

    How it works

    • The cap counts what your API requests cost this month, at your prices excluding GST, as listed under API products. A request that is not charged, such as a throttled one, does not count.
    • The count starts again at midnight on the first day of every month.
    • When usage passes 80% of the cap we email a warning to your member email and the alert addresses on your connection, with a copy to your billing email, at most once a day.
    • Once a request would take this month's usage up to the cap, it is refused with the scode err-developer-cap-reached and the message Cap has been reached for the month., and it is not charged. Every later request is refused the same way until the cap is raised or the month ends. A refused request does not top your account up either.
    • The cap is checked as each request starts, so requests already in progress when it is reached still complete and are charged. Usage can end slightly above the cap, by at most what those requests cost.

    Treat err-developer-cap-reached as "stop and tell a person". Retrying will not help.

    Changing your cap

    With account charging (the default on production), you can set or remove the cap yourself on the Developer page, under Cap. Otherwise contact us and we will change it for you.

    Set the cap a comfortable margin above what you expect to spend in a busy month: high enough that ordinary growth does not stop your integration, low enough that a leaked key or a bug is caught early. We recommend against removing the cap: without one, nothing limits what a leaked key can spend.

    The cap is about cost. How fast you may call is a separate limit: see throttling.

    —