API Keys

Key Format

API keys are prefixed with boxlive_ and consist of a key ID and a secret, separated by an underscore:

boxlive_01h455vb4pex5vsknk084sn02q_abc123def456xyz789

• Key ID (01h455...): used to identify the key in API responses and audit logs. Safe to log.
• Key secret (abc123...): shown only once at creation. Store it securely — it cannot be retrieved again.

Create a Key

curl -X POST https://api.boxowl.me/api/v1/orgs/acme/api-keys \
  -H "X-API-Key: boxlive_existingkey..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-vault-read",
    "scopes": ["vault:read", "connections:read"]
  }'

Response 201 Created:

{
  "keyId": "key_01h455vb4pex5vsknk084sn02q",
  "name": "production-vault-read",
  "key": "boxlive_01h455vb4pex5vsknk084sn02q_abc123def456xyz789",
  "scopes": ["vault:read", "connections:read"],
  "createdAt": "2026-04-27T12:00:00Z"
}

The key value is shown only now. Store it in your secrets manager immediately.

List Keys

Returns all keys for the organization. Key values are redacted. Note when each key was last used.

curl https://api.boxowl.me/api/v1/orgs/acme/api-keys \
  -H "X-API-Key: boxlive_existingkey..."

Response 200 OK:

{
  "keys": [
    {
      "keyId": "key_01h455...",
      "name": "production-vault-read",
      "scopes": ["vault:read", "connections:read"],
      "createdAt": "2026-04-27T12:00:00Z",
      "lastUsedAt": "2026-04-27T14:30:00Z"
    },
    {
      "keyId": "key_01h456...",
      "name": "staging-full",
      "scopes": ["vault:read", "vault:write", "vault:delete", "connections:read", "connections:write"],
      "createdAt": "2026-04-20T10:00:00Z",
      "lastUsedAt": null
    }
  ]
}

Rotate a Key

Key rotation generates a new secret for the same key ID. The old secret is invalidated immediately.

curl -X POST https://api.boxowl.me/api/v1/orgs/acme/api-keys/key_01h455.../rotate \
  -H "X-API-Key: boxlive_existingkey..."

Response 200 OK:

{
  "keyId": "key_01h455...",
  "key": "boxlive_01h455vb4pex5vsknk084sn02q_newsecretvalueXYZ",
  "rotatedAt": "2026-04-27T15:00:00Z"
}

Revoke a Key

curl -X DELETE https://api.boxowl.me/api/v1/orgs/acme/api-keys/key_01h455... \
  -H "X-API-Key: boxlive_existingkey..."

Response 204 No Content. The key is invalidated immediately and cannot be used for any future requests.

Security Best Practices

• Use separate keys per environment (dev/staging/prod)
• Apply the minimum scopes required — avoid vault:delete unless strictly needed
• Rotate keys regularly and immediately upon any suspected compromise
• Store key secrets in a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.) — never in source code
• Monitor lastUsedAt to detect unused keys