Authentication

Every request carries an API key as a bearer token:

curl https://api.flychain.us/external/v1/business_entities \
  -H "Authorization: Bearer $FLYCHAIN_API_KEY"

There is no OAuth flow, no token refresh and no per-provider consent step. This is the main operational difference from pulling reports out of a provider’s own accounting system: because you hold the credential rather than each provider, a provider joining Flychain needs no new authorization step on your side or theirs. They simply appear in GET /business_entities.

What a key can do

• Scoped to your partner relationship. A key reads only the providers in that relationship. A request for anything outside it is rejected — see Data semantics on how “not yours” is reported differently from “does not exist”.
• Read-only. Every endpoint on this API is a GET. There is nothing here that can modify data on our side.
• Not tied to a person. A key belongs to your organization, so it keeps working when the engineer who created it changes role.

Issuing, rotating and revoking keys

Key management lives in your Flychain partner dashboard. You can issue a key, set its expiry, rotate it and revoke it yourself, without a request to us.

When you create a key you give it a label and an expiry, and you must choose the expiry explicitly — there is no default. A key that never expires is a legitimate choice for a service integration; it should be a decision rather than something that happens by omission.

The key value is shown exactly once, at the moment it is created. Store it in your secret manager then. It cannot be retrieved afterwards — if it is lost, issue a new one and revoke the old one.

Rotating without downtime

You can hold more than one key at a time, which is what makes a clean rotation possible:

1. Create the new key.
2. Deploy it to every environment that calls this API.
3. Confirm traffic is flowing on the new key.
4. Revoke the old key.

There is no window in which neither key works, and no coordination with us. Do the same thing to retire a key you believe has been exposed — create, deploy, revoke — rather than revoking first and going dark in between.

Separate keys per environment

Hold a distinct key for each environment that calls us. A development key can then be revoked on its own without touching production, and the labels tell you which is which when you come back to the dashboard months later.

Handling authentication failures

Three responses look similar and mean different things. Distinguish them, because retrying the wrong one wastes hours and giving up on another loses a day of data.

Status	Code	What it means	What to do
401	INVALID_API_KEY	The key is missing, invalid, expired or revoked.	Stop and fix the credential. Retrying will not help.
403	PARTNER_API_NOT_ENABLED	Your key is fine. Your organization is not enrolled in the API programme.	Contact us to be enrolled. Do not rotate the key — a new one behaves identically.
503	AUTH_SERVICE_UNAVAILABLE	We could not check your key. Our identity provider was unreachable or rate-limited.	Retry with backoff. Your key is probably fine.

A 401 returns the same message whichever way the key failed — revoked, unknown, expired, or valid but on an organization that is not a partner. That is deliberate: the response cannot be used to learn which keys exist.

PARTNER_API_NOT_ENABLED is deliberately not folded into that 401. Enrollment is a setting on our side, so answering “invalid key” would send you off to rebuild an integration whose credential was never the problem.

Testing

There is no separate sandbox, deliberately. Every endpoint is a read-only GET, so there is nothing an integration can do to affect our data, and testing against real books is more informative than testing against synthetic ones. Build and test against live credentials from the start.

We will nominate a specific entity for you to develop against and confirm it alongside your key.