Onboarding and key lifecycle¶
This page covers how to get a FITIZENS partner API key, what to expect when you receive it, and what each key state means for your integration.
Requesting a key¶
Partner API keys are provisioned out-of-band by the FITIZENS operator. There is no self-serve signup form, no key-issuance endpoint, and no partner portal: every key starts with a human request.
To request access, email support@fitizens.io with a short description of your integration. The operator provisions a key on their side and sends it to you directly. There is no other channel for obtaining one.
No key yet?
You do not need a key to read this documentation. Email support@fitizens.io whenever you are ready, whether you are still evaluating or ready to integrate: that address is the only door in.
Receiving your key¶
The plaintext key is shown exactly once, at the moment it is provisioned. After that moment, only a one-way hash of the key is ever stored, so nobody, including the operator, can look it up or re-display it later.
Practically, this means:
- Save the key somewhere durable as soon as you receive it: a secrets manager, not a chat log or a note you might lose.
- If you lose it, there is no recovery path. The operator issues a replacement key instead. See What to do if your key stops working below.
Using your key¶
Keys are prefixed ftz_, so you can recognize a well-formed one, for
example ftz_your_key_here (a placeholder, not a real key).
Send it on every request as a bearer credential:
Treat the key as a secret. Keep it server-side only: never ship it in a mobile app, a browser bundle, or a public repository. Anyone who has the key can act as your integration until it is revoked.
Key states¶
Every key is in exactly one of three states, and the state determines what happens when it is used:
- Active. The key authenticates normally; requests proceed to the endpoint's usual behavior.
- Suspended. The operator has temporarily disabled the key. Requests fail immediately, the same way an invalid key would.
- Revoked. The key has been disabled. Requests fail immediately, the same way an invalid key would, and this cannot be undone: a revoked key never becomes active again.
Suspended, revoked, and invalid look identical to you¶
This is worth stating plainly: a suspended key, a revoked key, and a key that was simply mistyped or never existed all produce the exact same response. There is no separate error code, no status field, and no endpoint that tells you which of the three applies. The API only distinguishes active from not active, by design, so do not build integration logic that assumes you can tell them apart from the response.
What to do if your key stops working¶
If requests that used to succeed start failing with a 401
authentication_error (message: "Invalid, suspended, or revoked API
key."), your key is no longer active for one of the reasons above. See the
error catalog for the full shape of that response.
Contact support@fitizens.io. The operator can tell you what happened on their side and, if appropriate, issue a new key. There is no self-serve way to rotate or reinstate a key yourself: every path back to a working integration goes through that request.