Authentication

All Solenoid APIs authenticate via API keys passed as Bearer tokens in the Authorization header.

API Key Format

Keys follow the format sm_{entropy}_{checksum}:

sm_7kQ3mR9xLpW2nY5vB8tJ4cF6gH1dA0eS3iU7oP2qX_a1b2c3d4

Where:

• sm_ is the Solenoid platform prefix
• {entropy} is ~43 Base62-encoded random characters (A-Z, a-z, 0-9)
• {checksum} is an 8-character hex CRC32 checksum

The embedded checksum allows client-side format validation before making API calls. Keys match the regex pattern: ^sm_[A-Za-z0-9]+_[a-f0-9]{8}$

All endpoints under /v1/* require authentication.

Header Format

Authorization: Bearer sm_7kQ3mR9xLpW2nY5vB8tJ4cF6gH1dA0eS3iU7oP2qX_a1b2c3d4

Getting an API Key

Sign up at solenoid.systems/pricing.

Your API key will be emailed after signup. Paid tiers may take up to 60 seconds to propagate after payment confirmation.

Key Management

Storage

• Use environment variables, never hardcode
• Use a secret manager in production
• Never commit keys to version control

SOLENOID_API_KEY=sm_7kQ3mR9xLpW2nY5vB8tJ4cF6gH1dA0eS3iU7oP2qX_a1b2c3d4

Validation

Keys are self-validating via their embedded CRC32 checksum. Client libraries can verify the format before making network requests:

^sm_[A-Za-z0-9]+_[a-f0-9]{8}$

This catches typos and malformed keys before they reach the API.

Rotation

curl -X POST https://api.solenoid.systems/v1/keys/rotate \
  -H "Authorization: Bearer sm_7kQ3mR9xLpW2nY5vB8tJ4cF6gH1dA0eS3iU7oP2qX_a1b2c3d4"

{
  "key": "sm_9aB2cD4eF6gH8iJ0kL2mN4oP6qR8sT0uV2wX4yZ6aB_f8e7d6c5"
}

Grace period: Both the old and new keys remain valid for a brief grace period after rotation. The old key expires automatically, allowing you to update your applications without downtime.

Auth Errors

401 Unauthorized — missing or invalid API key:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Common causes:

• Missing Authorization header
• Invalid key format or typo
• Key has been revoked or the grace period after rotation has expired

429 Too Many Requests — rate limit exceeded:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded"
  }
}

See the API Reference for rate limits by tier.

Best Practices

• Use environment variables — never hardcode API keys
• Rotate quarterly — or immediately if compromised
• One key per environment — separate keys for dev, staging, production
• Monitor usage — watch for patterns that might indicate a leak