Authentication

All API requests require an X-API-Key header. API keys are scoped to a single tenant and support granular permissions.

Sending Your Key

Include the key in every request:

curl https://api.scootsign.com/api/v1/jds \
  -H "X-API-Key: aram_ent_a1b2c3d4e5f6..."

const res = await fetch("https://api.scootsign.com/api/v1/jds", {
  headers: { "X-API-Key": process.env.ARAM_API_KEY },
});

How Keys Work

Keys are prefixed with aram_ent_ for easy identification
Only the SHA-256 hash is stored — we never store keys in plaintext
The full key is shown only once when created — save it immediately
Keys can have an expiration date or be permanent
Each key tracks usageCount and lastUsedAt

Creating a Key

Use the dashboard or the API:

curl -X POST https://api.scootsign.com/api/v1/keys \
  -H "X-API-Key: aram_ent_ADMIN_KEY..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "scopes": ["read", "write"],
    "expiresInDays": 90
  }'

Important: Creating keys requires the admin scope.

Security Best Practices

Never hardcode keys in source code. Use environment variables or a secrets manager.
Use least-privilege scopes. If an integration only reads data, give it read scope only.
Rotate keys regularly. Set expiresInDays and create new keys before old ones expire.
Revoke unused keys. Delete keys that are no longer needed via DELETE /keys/:keyId.
Monitor usage. Check usageCount and lastUsedAt via GET /keys to detect anomalies.

Unauthorized Responses

If a key is missing, invalid, expired, or revoked:

{
  "success": false,
  "error": "Invalid or expired API key"
}

HTTP status: 401 Unauthorized

If the key is valid but lacks the required scope:

{
  "success": false,
  "error": "Insufficient scope: requires 'write'"
}

HTTP status: 403 Forbidden