API Keys & Automation

Programmatic access to your IPCraft data for scripts, CI/CD, and integrations.

Generating a Key

Go to Settings in the IPCraft app
Scroll to the API Keys section
Click Generate Key
Enter a name (e.g., "CI/CD Pipeline", "Monitoring Script")
Choose how long the key lasts: 30 days, 90 days (the default), 180 days, 1 year, or never. We email you two weeks before a key expires (keys that last longer than two weeks). An expired key stops authenticating with 401 API key expired; the list shows it as Expired until you revoke it
Copy the key immediately

The full API key is shown only once. If you lose it, you'll need to generate a new one.

Keys are prefixed with ipc_ for easy identification. The key prefix (first 12 characters) is visible in the settings page for reference. The number of live (unrevoked) keys you can have depends on your plan (5 on Free, 100 on Pro and Teams, 500 on Enterprise); expired keys count until you revoke them.

Using Your Key

Include the key in the Authorization header:

curl https://api.ipcraft.io/api/v1/subnets \
  -H "Authorization: Bearer ipc_a1b2c3d4e5f6..."

API key requests don't need the X-Requested-With header (that's only for browser session auth).

Permissions

Each key carries its own permission scopes: read, write, or both (the default). When creating a key via the API (a browser session is required: an API key cannot mint keys), pass "permissions": ["read"] to mint a read-only key — a good default for dashboards and monitoring.

Your plan adds a second layer on top of key scopes:

Free plan: API access is read-only. GET requests work, but POST/PATCH/DELETE return 403 regardless of the key's scopes.
Pro, Teams, and Enterprise: Full read/write access to all endpoints (subject to the key's scopes).

Example: List Subnets

curl -s https://api.ipcraft.io/api/v1/subnets \
  -H "Authorization: Bearer ipc_your_key_here" \
  | python3 -m json.tool

Example: Assign an IP

curl -X POST https://api.ipcraft.io/api/v1/subnets/{subnet_id}/addresses \
  -H "Authorization: Bearer ipc_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "10.0.1.50",
    "hostname": "web-server-03",
    "status": "assigned",
    "owner": "ops-team"
  }'

Example: Find Next Available IP

curl -s https://api.ipcraft.io/api/v1/subnets/{subnet_id}/first-free \
  -H "Authorization: Bearer ipc_your_key_here"

# Response: {"ip": "10.0.1.51"}

Example: Bash Script

#!/bin/bash
# Assign the next available IP in a subnet
API="https://api.ipcraft.io/api/v1"
KEY="ipc_your_key_here"
SUBNET_ID="your-subnet-uuid"

# Get next free IP
FREE_IP=$(curl -s "$API/subnets/$SUBNET_ID/first-free" \
  -H "Authorization: Bearer $KEY" | jq -r '.ip')

if [ "$FREE_IP" = "null" ]; then
  echo "No available IPs"
  exit 1
fi

# Assign it
curl -X POST "$API/subnets/$SUBNET_ID/addresses" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{\"ip\": \"$FREE_IP\", \"hostname\": \"$(hostname)\", \"status\": \"assigned\"}"

echo "Assigned $FREE_IP"

Two copies of this script running at once can read the same free IP. If the subnet is an IP pool, leave ip out of the create and the API picks the next free address itself, one per request, and returns it in the response (jq -r '.ip'). See auto-assign.

Revoking Keys

Click the trash icon next to any key in Settings to revoke it immediately. Revoked keys stop working instantly. Expired keys stop working on their own but keep their slot toward your plan’s key limit until you revoke them.

For security, rotate your API keys periodically and use separate keys for different integrations so you can revoke one without affecting others.

Rate Limits

API key requests share the same rate limits as the web application. There are no separate per-key rate limits at this time.

See the full API reference for all available endpoints.