Skip to main content
Pre-release — contact your Fortary account team for access.
This page collects the practices that keep an integration secure and resilient. The details live on the concept pages linked throughout; this is the short version to read before you go to production.

​
Keeping your API key secure

An API key authenticates against your organization’s real custody data. Treat the secret like a production password.
  • Store it in a secrets manager, not in source code, configuration files, or environment files committed to version control. Never embed a key in client-side or browser code — the API is a server-to-server surface.
  • Scope every key to the least it needs. Give a key the narrowest vault allowlist that lets it do its job, so a single leaked key can never reach vaults it didn’t need. See Authorization and Scopes.
  • Bind keys to your network. Set an IP allowlist of your servers’ egress ranges so a leaked secret is useless from anywhere else.
  • Keep a finite expiry and rotate. Leave the default 365-day expiry in place unless you have a reason to change it, and rotate long-lived keys periodically by creating a new key and revoking the old one.
  • Use one key per integration and environment, so you can revoke or rotate one without disrupting the others.
If a key is leaked, revoke it immediately. Revocation takes effect at once across the API. Don’t rely on removing the owner’s role for an emergency cutoff — role changes may take up to 5 minutes to propagate, so revoke the key directly. See revoke and rotate.

​
Building a resilient integration

The API’s conventions are designed so a well-built client keeps working across releases. The practices below come straight from those conventions.
  • Ignore unknown response fields. New optional fields are added within a version without a version bump — a client that tolerates them won’t break on additive changes. See the versioning policy.
  • Treat identifiers and cursors as opaque. Store and pass back the exact strings you receive; don’t parse or construct vault IDs or pagination cursors. See Identifiers & data formats and Pagination.
  • Page with the cursor, not a total. Follow nextCursor until it is null rather than assuming a fixed number of pages; responses don’t carry a total count. See Pagination.
  • Parse amounts with a decimal library, never a float. All amounts are JSON strings to preserve precision. See Identifiers & data formats.
  • Back off and retry transient failures. Retry 429, 500, and 503 with exponential backoff plus jitter, and honor the Retry-After header. Don’t retry 400, 401, 403, 404, or 422 — they won’t succeed without a change to the request or credential. See Rate limiting.
  • Pace yourself before you hit a limit. Watch X-RateLimit-Remaining and slow down as it approaches zero rather than waiting for a 429. See Rate limiting.
  • Branch on type/code and the HTTP status, never on the message. The codes are part of the contract; the wording is not. See Errors.
  • Watch for deprecation signals. A retiring version returns Deprecation and Sunset headers; detect them in your monitoring so a migration is never a surprise. See the deprecation policy.

​
Getting help

Every response carries an X-Request-Id header, mirrored in error bodies as correlationId. Capture it in your logs — quoting it when you contact your Fortary account team lets support trace exactly what happened on a specific request. See Errors.