Skip to main content
Authenticate every request with an API key in the x-api-key header.
The host api.fawcos.com is a placeholder until the production host is announced.

​
Test and live keys

The prefix is part of the key and decides the environment. A test key can never return a real farmer’s data, and a live key can never return a synthetic one. Test and live keys are separate: a key from one environment does not work in the other. Keys issued before the FWS_ prefix (they start fawcos_test_ or fawcos_live_) keep working until you rotate them.

​
Who can create keys

Organisation administrators create and manage keys in the FaWCOS enterprise dashboard. Each key has a name and one or more scopes. You can hold up to five active keys per environment, for example one per system.

​
Handling keys

A key is shown once, when you create it. FaWCOS stores only a hash, so a lost key cannot be recovered: create a new one.
  • Store keys in a secrets manager or environment variable. Never put them in source control, logs, screenshots, support tickets, mobile apps or browser code.
  • Give each system its own key with the narrowest scopes it needs.
  • Never use a live key where a test key will do.

​
Rotating and revoking

  • Rotate. Rotating creates a replacement with the same name, scopes and limits. The old key keeps working for an overlap you choose (60 minutes by default, up to 7 days) so you can deploy the new one without downtime. Set the overlap to 0 to end the old key at once.
  • Revoke. A revoked key stops working immediately.
  • If you suspect a key has leaked, revoke it first and create a new one.

​
Authentication errors

A rejected key never says which part was wrong. See Errors for the full list.