API Key Authentication for Court Data: Best Practices

Ask a developer what a leaked court data API key costs and the answer is usually reassuring. The data is public. Judgments are published. Somebody would get some case records they could have looked up themselves on a government portal. Annoying, a bit of billing exposure, not a crisis.

That answer is wrong, and it is wrong in a way specific to legal work. The exposure is not the case records. It is the query log. Every authenticated call is logged against the key that made it, which means anyone holding your key, and anyone who obtains the log, can see which parties your firm searched, which statutory provisions you pulled, which High Courts you filtered to, and, most tellingly, when you started looking.

Consider what that reveals. A sequence of searches against a named company, followed by queries about section 34 of the Arbitration and Conciliation Act 1996, followed by a sweep of NCLT filings involving that company's subsidiaries, is not a data leak. It is your case theory, six weeks before you file. A research trail is work product, and in the hands of the counterparty it is worth considerably more than the judgments it retrieved.

That is the argument of this piece: legal data credentials deserve the hygiene you already apply to payment credentials, and for a reason payments do not have, which is that the queries themselves are privileged strategy. What follows is how to actually do it, grounded in how the CourtMesh API issues and tracks keys, with the endpoint reference.

What a Leaked Key Actually Exposes

Set out the exposure properly, because the mitigation only makes sense once the threat is stated accurately.

Notice that only the last of these is a conventional API security problem. The first three are confidentiality problems, and they are governed by obligations that predate every API you have ever integrated. An advocate's duty of confidence to a client extends to the fact of the retainer and to the work done under it. A research trail is work done under it.

The judgments are public. The fact that your firm was reading them, in that order, starting on that date, is not.

How the Credential Actually Works

Good hygiene follows from understanding the mechanism, so here is the mechanism precisely.

A key is presented on every authenticated request in one of two headers: X-API-Key carrying the key, or Authorization carrying Bearer followed by the key. Either is accepted, so choose whichever your HTTP client handles most reliably and be consistent. Keys have a defined shape: a prefix, then 32 base64url characters, then a four character suffix, in the form cm-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XXXX. Legacy keys issued with a vv- prefix continue to work. GET /health is the only endpoint that requires no key at all.

The property that should shape everything you do next: keys are stored server side only as bcrypt hashes. The plaintext is displayed once, at creation, and cannot be recovered afterwards by you, by support, or by anyone with database access. There is no lookup that returns your key.

This is the correct design and it is worth understanding why. A hashed credential store means that a breach of the provider's database does not hand an attacker working keys. It also means that any provider whose support team can read your key back to you is storing it reversibly, and their database is a single point of catastrophic failure for every customer at once. When you evaluate a legal data vendor, ask whether support can recover a lost key. The right answer is no, and a vendor who offers the convenience is telling you something important about their storage.

The Rules, and Why Each One Exists

Never ship a key in client code

This is the one that still causes most incidents, and the reasoning is often subtly wrong rather than absent. Developers know not to commit a key to a public repository. Fewer internalise that any key present in a browser bundle, a mobile application binary, or a desktop application is already public, whatever the repository's visibility. Minification is not obfuscation. A single view-source, or a few minutes with a decompiler, retrieves it.

The correct architecture is unambiguous: the key lives on your server, your client talks to your server, and your server talks to the court data API. That backend proxy is not overhead. It is where you enforce your own authorisation, apply your own rate shaping ahead of the 10 requests per minute limit on API key traffic, cache case records so you are not spending budget refetching a judgment that has not changed since 1994, and log which of your users searched what.

That last point deserves emphasis. Without a proxy you have one key making all calls, and your provider's per key log shows one blended stream. With a proxy you know which of your users ran which query, which is exactly the record you need when a partner asks who searched a particular counterparty.

One key per environment and per workload

The single shared key is convenient for about a month. Then it becomes the thing that makes every incident maximally expensive, because revoking it takes down production, staging, the nightly ingestion job and the partner integration simultaneously.

Split by environment first: development, staging and production never share a credential. Then split by workload, which is the part teams skip. Your interactive user facing path and your overnight backfill should hold different keys even in the same environment. Two reasons. Revocation becomes narrow: a leaked backfill key is revoked without a lawyer losing their search box. And attribution becomes possible: because every call is logged per key, separate keys mean you can see immediately which workload consumed the rate budget or burned the AI credits, instead of inferring it from timestamps.

Rotate on a schedule, and rotate without downtime

Rotation is unpopular because most teams have only ever done it in an emergency, where it is stressful and error prone. Done routinely it is dull, and dullness is the objective: a rotation you have performed four times without incident is a rotation you can perform confidently at nine at night when a key has leaked.

Monitor per key, and know what normal looks like

Every authenticated call is logged against the key that made it: endpoint, method, status code, response time, sanitised headers, query parameters and body, IP address and user agent, with lastUsedAt updated on every call. Sensitive header and body values, including authorization, cookie, x-api-key, password, token and secret, are redacted before storage, so a key that your own client accidentally echoes into a request body does not end up sitting in a log.

That log is a detection capability, and it is wasted unless somebody has decided what normal looks like. Establish a baseline for each key: which endpoints it touches, roughly what volume, from which IP ranges, at which hours. Then alert on deviation.

• A key calling an endpoint it has never called. Your batch ingestion key suddenly hitting the semantic search endpoint is either an undocumented feature launch or somebody else holding your credential.
• Traffic from an unexpected IP or user agent. A production key whose calls have always come from two static addresses now arriving from a residential connection is worth an immediate look.
• Volume outside the pattern. Sustained calls at the ceiling of 10 requests per minute from a key that normally runs at a fraction of that, particularly outside working hours.
• A rise in 401 responses. Repeated authentication failures against your account can be an attacker probing formats, or your own rotation half completed. Both need attention and the log distinguishes them.
• 403 responses on AI endpoints. Credit exhaustion is a billing state, not a credential failure, and it deserves its own alert. An unexplained one means somebody is spending your allowance.
• lastUsedAt on a key you believed was dormant. The single cheapest check available. A retired key that is still being used has not been retired.

The Legal Layer: DPDP 2023 and Professional Confidence

Credential hygiene here is not only an engineering preference. Two distinct sets of obligations sit on top of it, and they point the same way.

The first is statutory. Under the Digital Personal Data Protection Act 2023, an entity determining the purpose and means of processing personal data is a data fiduciary, with duties including implementing reasonable security safeguards to prevent personal data breach, and obligations of notification when a breach occurs. Court records are full of personal data: parties, addresses, and in many matter types information that is sensitive by any ordinary reading. When you retrieve that data through an API and store it in your own systems, you are processing it, and the key controlling that retrieval is one of your safeguards. A credential shipped in a mobile binary is not a reasonable security safeguard, and it will not be easy to characterise as one after the fact.

The second is professional and older. Confidentiality between advocate and client is not limited to the contents of a communication. It extends to the existence of the retainer and to the work carried out under it. Legal research is that work. A query log showing sustained research into a named counterparty, particular provisions and particular forums is a record of privileged strategy, held in a system whose access control is a single string.

Which is the whole argument compressed: a payment credential, if leaked, exposes money, and money is recoverable. A legal research credential, if leaked, exposes strategy, and strategy is not recoverable once the other side has seen it. The case for treating court data keys with payment grade hygiene is not that the data is equally sensitive. It is that the disclosure is less reversible.

How Keys Actually Leak

Almost none of these are sophisticated. They are the same handful, repeating, and each is preventable by a decision taken before the code is written.

If a key does leak, the sequence is short and should be rehearsed. Issue a replacement first, deploy it, verify it is carrying traffic, then deactivate the compromised key so that any further use returns 401. Then read the per key transaction log for the exposure window and answer the question that actually matters to a professional obligation: which queries were run on that key while it was out of your control, and whose matters do they touch. That question is not answerable at all without per key logging, which is why the logging is a control and not merely a billing convenience.

A Standard Worth Holding

None of this is exotic. It is the same discipline applied to payment credentials, which most engineering teams already accept without argument. The only reason it is applied less consistently to legal data is a mistaken belief that public records cannot be sensitive.

They cannot be, in isolation. A judgment of a High Court is published and citable and belongs to everyone. But a pattern of retrieval is not a judgment. It is a description of what a firm is working on, for whom, and since when, assembled by the firm itself and stored behind one string. Treat the string accordingly: created once and captured into a secret manager immediately, held only on servers you control, scoped narrowly enough that revocation is cheap, rotated on a schedule you have practised, and monitored against a baseline somebody actually established.

The provider side of this is visible and worth checking on any vendor you consider. Keys stored as bcrypt hashes with no recovery path. Two accepted header forms. Distinct 401 messages that tell you whether a credential was missing, malformed, unrecognised or deactivated. Per key transaction logging with sensitive values redacted before storage, and lastUsedAt updated on every call. Rate limit headers on every response and a 429 carrying a retry interval rather than leaving you to guess. Those details are documented in the endpoint reference, and the credit consumption that a stolen key would be spending is published at API pricing.