API Key Authentication

Overview

NxVET uses API Key authentication for programmatic access to the REST API. API keys provide secure, organization-scoped access to NxVET data.

Key Features

• Organization-scoped: Each key is bound to a single organization
• Instant revocation: Revoked keys are immediately invalidated
• Optional expiration: Set an expiry date or create keys that never expire
• Usage tracking: Last-used timestamps for auditing
• Self-service: Create and manage keys through the NxVET Integrations page

Quick Start

Get up and running in under 2 minutes:

1. Generate an API key in the NxVET Integrations page → API Keys tab
2. Copy the key and organization ID immediately (the key is shown only once!)
3. Verify your key and discover your org ID with /api/auth/me:

# Step 1: Verify your key and get your organization ID
curl -H "Authorization: Bearer nxvet_sk_YOUR_API_KEY" \
  "https://app.nx.vet/api/auth/me"

# Step 2: Use the organizationId from the response
curl -H "Authorization: Bearer nxvet_sk_YOUR_API_KEY" \
  "https://app.nx.vet/api/devices?organizationId=YOUR_ORG_ID&limit=10"

const API_KEY = process.env.NXVET_API_KEY;
const headers = { 'Authorization': `Bearer ${API_KEY}` };

// Step 1: Verify key and get organization ID
const me = await fetch('https://app.nx.vet/api/auth/me', { headers })
  .then(r => r.json());
const ORG_ID = me.organizationId;
console.log(`Org: ${me.organizationName} (${ORG_ID})`);

// Step 2: List devices
const devices = await fetch(
  `https://app.nx.vet/api/devices?organizationId=${ORG_ID}&limit=10`,
  { headers }
).then(r => r.json());
console.log(devices);

import os, requests

API_KEY = os.environ['NXVET_API_KEY']
headers = {'Authorization': f'Bearer {API_KEY}'}

# Step 1: Verify key and get organization ID
me = requests.get('https://app.nx.vet/api/auth/me', headers=headers).json()
ORG_ID = me['organizationId']
print(f"Org: {me['organizationName']} ({ORG_ID})")

# Step 2: List devices
devices = requests.get(
    'https://app.nx.vet/api/devices',
    params={'organizationId': ORG_ID, 'limit': 10},
    headers=headers
).json()
print(devices)

Getting API Keys

Prerequisites

• A NxVET account with organization owner or NxVET admin role
• At least one organization associated with your account

Creating a Key via the UI

1. Log in to app.nx.vet
2. Navigate to the Integrations page → API Keys tab
3. Click "Create API Key"
4. Enter a descriptive name (e.g., "Production Integration")
5. Select the organization this key should access
6. Optionally set an expiration date
7. Click Create

Creating a Key via the API

You can also create keys programmatically (requires an existing authenticated session):

curl -X POST "https://app.nx.vet/api/api-keys" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "organizationId": "YOUR_ORG_ID",
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

Response:

{
  "id": "019e1234-5678-7000-abcd-123456789abc",
  "name": "Production Integration",
  "keyPrefix": "nxvet_sk_a1b2c3d4...",
  "key": "nxvet_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "organizationId": "0185644d-9383-7000-b35d-6e31e1158b43",
  "createdAt": "2026-02-20T17:45:00Z",
  "expiresAt": "2027-01-01T00:00:00Z"
}

Using API Keys

Authorization Header

Include your API key in the Authorization header of every request:

Authorization: Bearer nxvet_sk_YOUR_API_KEY

Error Responses

Identity & Organization ID Discovery

Use GET /api/auth/me to discover your organization ID and verify your API key is working. This is the recommended first API call for any integration.

curl -H "Authorization: Bearer nxvet_sk_YOUR_API_KEY" \
  "https://app.nx.vet/api/auth/me"

const response = await fetch('https://app.nx.vet/api/auth/me', {
  headers: { 'Authorization': `Bearer ${process.env.NXVET_API_KEY}` }
});

const me = await response.json();
console.log(`Organization ID: ${me.organizationId}`);
console.log(`Organization: ${me.organizationName}`);
console.log(`Auth method: ${me.authMethod}`);

import os, requests

response = requests.get(
    'https://app.nx.vet/api/auth/me',
    headers={'Authorization': f'Bearer {os.environ["NXVET_API_KEY"]}'}
)

me = response.json()
print(f"Organization ID: {me['organizationId']}")
print(f"Organization: {me['organizationName']}")
print(f"Auth method: {me['authMethod']}")

Response

{
  "userId": "019a6f14-0353-7000-b716-1ed06d8fb74c",
  "email": "vet@example.com",
  "authMethod": "ApiKey",
  "organizationId": "0185644d-9383-7000-b35d-6e31e1158b43",
  "organizationName": "Example Vet Clinic",
  "apiKey": {
    "id": "019e1234-5678-7000-abcd-123456789abc",
    "name": "Production Integration",
    "keyPrefix": "nxvet_sk_a1b2c3d4...",
    "createdAt": "2026-02-20T17:45:00Z",
    "expiresAt": "2027-01-01T00:00:00Z"
  }
}

Response Fields

Key Management

Listing Keys

View all your API keys (full keys are never shown after creation):

curl -H "Authorization: Bearer nxvet_sk_YOUR_API_KEY" \
  "https://app.nx.vet/api/api-keys"

Each key in the response includes:

• keyPrefix — First 8 characters for identification (e.g., nxvet_sk_a1b2c3d4...)
• lastUsedAt — Timestamp of last API request
• isRevoked — Whether the key has been revoked
• expiresAt — Expiration date (null if no expiration)

Revoking Keys

Revoke a key immediately. This cannot be undone.

curl -X DELETE -H "Authorization: Bearer nxvet_sk_YOUR_API_KEY" \
  "https://app.nx.vet/api/api-keys/KEY_ID"

Returns 204 No Content on success. All subsequent requests using the revoked key will receive 401 Unauthorized.

Security Best Practices

• Use environment variables — Never hardcode keys in source code
• Rotate regularly — Create new keys and revoke old ones periodically
• One key per integration — Use separate keys for each service or environment
• Never expose client-side — API keys must only be used from server-side code
• Monitor usage — Check lastUsedAt to detect unused or compromised keys
• Set expiration dates — Use expiresAt for time-limited integrations
• Revoke immediately — If a key is compromised, revoke it right away

Example: Using Environment Variables

// .env file:
// NXVET_API_KEY=nxvet_sk_your_key_here

const apiKey = process.env.NXVET_API_KEY;

const response = await fetch('https://app.nx.vet/api/devices?organizationId=YOUR_ORG_ID', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

import os
import requests

# .env file or system environment:
# NXVET_API_KEY=nxvet_sk_your_key_here

api_key = os.environ['NXVET_API_KEY']

response = requests.get(
    'https://app.nx.vet/api/devices',
    params={'organizationId': 'YOUR_ORG_ID'},
    headers={'Authorization': f'Bearer {api_key}'}
)

Implementation Checklist