API Keys
Manage your API keys to authentication requests with Falu
Falu authenticates your API requests using your workspace's API keys. You will receive an error if you don't include your key when making an API request, or use an incorrect or outdated one.
Every workspace has separate keys for testing and running live requests. All API requests exist in either test or live mode, and objects in one mode (messages, payments, identities, etc.) can't manipulate objects in the other.
There are also two types of API keys: public and secret:
- Public API keys are solely meant to identify your workspace with Falu; they aren't secret and you can safely publish them in places like your JavaScript code, or in an Android or iOS app.
- Secret API keys must be kept confidential and only stored on your own servers. You must not share them with any third parties. Your workspace's secret API keys can perform any API request to Falu unless restricted. If Falu believes that your secret API key has been compromised, we may cancel and reissue it, potentially resulting in an interruption of services to your application(s).
By default, each workspace has a total of four keys: a public and secret key pair for test mode and live mode. The pair for live mode are only created when a workspace is approved.
Obtaining your API keys
Your API Keys are always available in the Dashboard. For example, your API Keys could look like:
| Key | Value |
|---|---|
| Publishable | fpkt_rFBfqDcayL3PigQ7xA2Ipy5NsUzr9q9Ld8TxBn3HCvg |
| Secret | fskt_LdVyn0upNzbQTSPYZ3aF7NAJlXPjcTECYVbIuuu8Ys |
Only use your test API keys for testing and development to ensure that you don't accidentally modify your live resources.
If you don't have an administrator or developer role, you may not have access to your API keys in the Dashboard. Contact your Falu workspace owner and ask to be added to their team as a developer.
Test and live modes
The test and live modes function almost identically, with a few necessary differences:
- In test mode, payments are not processed by card networks or payment providers, and only your test payment information can be used.
- Some payment methods have a more nuanced flow in live mode, with more steps required than those in test mode.
- In test mode, messages are not processed by mobile network providers, and only your test messaging information can be used.
- In test mode, Webhooks that were not successfully acknowledged are retried only 3 times over a few hours, as opposed to 72 hours for live mode.
- In test mode, Identity does not perform any verification checks.
You can view test data by toggling the Dashboard's Live/Test switch on the top right.
Keeping your keys safe
Your secret API key can be used to make any API call on behalf of your workspace, such as creating payments or performing refunds.
Treat your secret API key as you would any other password: Grant access only to those who need it; ensure it is kept out of any version control system you may be using; control access to your keys using a password manager or secrets management service.
In live mode, new secret keys are only visible the first time you access them, after which they are redacted. If you lose your secret key, you can't recover it from the Dashboard and must roll the key or create another one.
Rolling keys
If an API key is compromised, roll the key in the Dashboard to block it and generate a new one.
When rolling an API key, the old key immediately becomes invalid. If you need time to make transitions, create a new key first and make the transitions before rolling.
Limiting access on API keys
Your workspace's secret API keys can be used to perform any API request without restriction by default. For greater security, you can restrict the permissions that an API key has access to. Restrictions are particularly useful if you're working with micro-services that interact with the Falu API on your behalf.
Restricting a key allows only the minimum level of access that the service needs while protecting workspace data. For example, you can restrict a key to messages, then use it with a messages monitoring service.
Restricting the networks allowed for a given API key provides greater control over the traffic flow, further ensuring that only traffic from your own servers can make requests to Falu.
Clearing all permissions or networks allows the key to have unrestricted access to resources or from networks respectively.
Permission restrictions are intended to reduce risk when using or building micro-services. They are not to be used as an alternative to your workspace's API keys during development of your Falu integration. An API key with restricted permissions cannot interact with many parts of Falu's API. Use your test API keys during development and live API keys once your integration is live without restrictions.