> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casepathiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and environments

> Authenticate a partner integration and understand Client-scoped authorization.

CasePath IQ uses environment-specific Bearer keys for server-to-server authentication.

```http theme={null}
Authorization: Bearer <partner-key>
```

Keys are displayed once when provisioned and stored by CasePath IQ only as secure verifiers. Send them over HTTPS and keep them in a secrets manager.

## Authentication and authorization

Authentication and authorization are separate:

1. The Bearer key identifies one Source integration.
2. Current grants determine which Client codes that integration may access.

CasePath IQ checks the Client grant before looking up a resource. Unknown and unauthorized Client codes return the same generic `403 client_scope_denied` response. A request body or key cannot assert its own Client authority.

After that grant check, every Matter, Payment observation, and synchronization query is also scoped to the authenticated Source integration. Records from another Source, manual intake, a Legal matter referral, an unknown identifier, or another Client return the same neutral `404` without revealing whether they exist.

## Environments

| Boundary | Sandbox | Production |
| - | - | - |
| Base URL | `https://api.sandbox.casepathiq.com` | Supplied separately at onboarding |
| Keys and grants | Separate | Separate |
| Database and data | Synthetic test data | Live authorized data |
| Outbound activity | Live providers disabled | Test flags rejected |
| Network controls | Environment-specific | Environment-specific |

> [!NOTE]
>
> Sandbox API requests need only an issued Sandbox key and its authorised Client code. Microsoft sign-in is for staff managing keys. Production onboarding and credentials are separate.

Use the exact base URL supplied during onboarding. A sandbox key cannot access production, and production does not accept sandbox flags.

## Handle keys safely

Never place a key in:

* A URL or query string
* A browser or mobile client
* Source control
* Tickets, chat, screenshots, or support messages
* Application logs or tracing attributes

CasePath IQ logs the route template, key identifier, outcome, and request ID—not Bearer credentials, request bodies, raw path identifiers, contact details, or notes.

## IP restrictions

New Sandbox keys issued without IP ranges work from any public IPv4 or IPv6 address. Existing restricted keys retain their ranges. Production key issuance requires approved outbound CIDR ranges: no `/0`, nothing wider than `/24` for IPv4 or `/48` for IPv6, and no private, loopback, link-local, documentation, multicast or reserved range. Restricted keys reject missing, malformed or unapproved source addresses with the same neutral `401 invalid_credentials` as an unknown or expired key.

## Restrict a key to some Clients

By default a key reaches every Client its Integration is authorised for. When a key is created it can instead be limited to a chosen subset of those Clients; any other Client code returns `403 client_scope_denied`, the same response as an unknown Client code.

## Archived Firms

When the Firm that issued a key is archived, every one of its keys returns the same neutral `401 invalid_credentials` and nothing is written. The keys work again if the Firm is restored.

## Key expiry

Keys expire 180 days after creation. The API keys page lists each key's IP ranges and flags a key that expires within 14 days, so a replacement can be created and deployed before the old key is revoked.

## Rotate or revoke a key

**1. Provision a replacement**

Create the new environment-specific key while the old key remains valid during the agreed overlap.

**2. Deploy the replacement**

Update the partner system through its secrets-management process.

**3. Verify traffic**

Confirm successful requests use the new key and expected Client grants.

**4. Revoke the old key**

Revoke the previous key after verification.

Authorization is checked on every request, including identical retries. A revoked key or removed Client grant cannot reuse an earlier successful receipt.

## Next

* [Create a sandbox Matter](https://docs.casepathiq.com/quickstart.md)
* [Understand Client and Matter identity](https://docs.casepathiq.com/concepts.md#partner-and-case-path-iq-identifiers)
* [Handle authentication and scope errors](https://docs.casepathiq.com/errors-and-retries.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.