Authentication & API Key Management

API Keys

Proxiant uses bearer token authentication. Every API request must include an API key in the Authorization header.

Key Format

Keys are prefixed to make them easy to identify and to enable secret scanning in your repositories:

prx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx PRODUCTION

fh_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx SANDBOX (coming soon)

⚠️

Keys are shown only once. Copy and store your key immediately after generating it. We do not store a recoverable copy — if you lose it, you'll need to revoke it and generate a new one.

Generating a Key

Navigate to API settings

Go to Settings → API → New Key in your Proxiant dashboard.

Name your key

Use a descriptive name that identifies what the key is for — e.g., "QuickBooks Integration", "Custom Dashboard", "Zapier". This makes it easy to identify and revoke the right key if needed.

Select permission scopes

Choose only the scopes your integration needs. See the Permission Scopes table below for the full list.

Copy the key

The full key is displayed once. Copy it now and store it securely — in an environment variable, a secrets manager, or your CI/CD vault. Never store it in source code or commit it to a repository.

Using a Key

Pass your key in the Authorization header using the Bearer scheme. This header is required on every API request.

bash

# List all jobs
curl https://api.proxiant.co/v1/jobs \
  -H "Authorization: Bearer prx_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

javascript

const response = await fetch('https://api.proxiant.co/v1/jobs', {
  headers: {
    'Authorization': `Bearer ${process.env.PROXIANT_API_KEY}`,
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

python

import os, requests

headers = {
    "Authorization": f"Bearer {os.environ['PROXIANT_API_KEY']}",
    "Content-Type": "application/json"
}
resp = requests.get("https://api.proxiant.co/v1/jobs", headers=headers)
data = resp.json()

Requests without a valid key receive a 401 unauthorized response. Requests using a key that lacks a required scope receive 403 forbidden.

Permission Scopes

Each key has a set of scopes that determine what it can do. Grant only the scopes your integration actually needs — this limits the blast radius if a key is ever compromised.

Scope	Allows
jobs:read	List jobs, get job details, search and filter jobs
jobs:write	Create new jobs, update existing jobs, change status
attempts:read	List and read service attempts on jobs
attempts:write	Log new service attempts, upload attempt photos
clients:read	List clients, read client details and billing config
clients:write	Create and update client records
invoices:read	Read and list invoices; does not allow creation or modification
affidavits:read	List affidavits, read details, download PDFs
webhooks:manage	Create, list, and delete webhook subscriptions

💡

Read and write scopes are separate for every resource. A read-only integration dashboard should only have :read scopes — never :write.

Key Management

Manage your API keys from Settings → API in your Proxiant dashboard.

Detail	Value
Max keys per firm	10 active keys
Expiration	Keys do not expire automatically — revoke when no longer needed
Last used	Visible per-key in Settings → API (updates in real time)
Revocation	Immediate — click Revoke, key stops working instantly, cannot be undone

The key listing page shows name, created date, last used timestamp, and active scopes for every key. You cannot retrieve the full key value again after creation — only the first few characters are shown for identification.

⚠️

Revocation is permanent. Revoking a key immediately and permanently disables it. Any integrations using that key will stop working. Generate a replacement before revoking if you need continuity.

Security Best Practices

🔒

Never put keys in client-side code

API keys should only live in server-side code, environment variables, or secrets managers. Any key in a browser, mobile app, or public repository should be considered compromised.

📦

Use environment variables

Store keys as environment variables (PROXIANT_API_KEY) and read them at runtime. Never hard-code them as string literals.

🔑

One key per integration

Create a separate key for each integration or application. This makes it easy to revoke a specific integration's access if it's compromised, without disrupting others.

🎯

Use minimal scopes

Grant only the scopes an integration actually needs. A reporting dashboard only needs jobs:read, clients:read — not write access to anything.

🔄

Rotate keys periodically

Create a new key, update your integration to use it, then revoke the old one. Even if a key hasn't been compromised, regular rotation limits the window of exposure.

🚨

Revoke immediately if compromised

If you suspect a key has been exposed, revoke it immediately from Settings → API. Check your access logs for unexpected usage patterns before creating a replacement.

bash — .env example

# .env (never commit this file)
PROXIANT_API_KEY=prx_live_xxxxxxxxxxxxxxxxxxxx

# .env.example (safe to commit — no real key)
PROXIANT_API_KEY=prx_live_your_key_here