Authentication and keys

Every request except health checks carries an API key as a bearer token.

Authorization: Bearer vf_test_...

Key format

Environment	Prefix	Example shape
Sandbox	vf_test_	vf_test_ followed by 43 URL-safe characters
Production	vf_live_	vf_live_ followed by 43 URL-safe characters

A key carries 32 bytes of randomness. VelociFile stores only a SHA-256 hash of it, plus the first 12 characters and the last four, so staff and your administrators can recognize a key without ever seeing it again. The full key is shown once, to the VelociFile staff member who issues it.

A key works only in its own environment. A sandbox key sent to the production host is rejected with 401 UNAUTHORIZED, and the reverse.

One active key per account

Each account has exactly one active key per environment. This is enforced by the database, so there is no overlap window where two keys work.

• Issue. Creating a key when one is already active fails with 422 CAPABILITY_UNSUPPORTED. Rotate instead.
• Rotate. Creates the new key and revokes the old one in a single transaction. The new key works immediately. The old key stops working immediately and is rejected on every server within 30 seconds, because servers cache key lookups for at most 30 seconds. Plan rotations so that you can deploy the new key at once.
• Expire. Revokes the active key without a replacement. A key can also carry an optional expiry date, after which it is rejected.

Only VelociFile staff can issue, rotate or expire keys. Your own administrators get a read-only view of key metadata (prefix, last four characters, created, last used, expiry) in the VelociFile admin area.

Failed authentication

A missing, malformed, revoked, expired or wrong-environment key answers:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
X-Request-Id: req_...

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key.",
    "request_id": "req_...",
    "retryable": false
  }
}

A valid key that is not entitled to the requested data answers 403 FORBIDDEN.

Handling keys

• Keep keys on your servers. Do not ship them in browsers, mobile apps or public repositories.
• Read them from the environment or a secrets manager.
• If a key is exposed, ask VelociFile to rotate it. The old key stops working at once.
• The try-it console in this portal sends your key from your browser straight to the API and does not store it. Use a sandbox key there.