An API Key is linked to an API Version.
To see the API version your API Key is using fetch your API keys with the Get API Keys endpoint see the API Keys doc and reference the apiVersion field.
Therefore, if you are using an API key in your application your application is effectively "pinned" to use a particular API Version.
When you create an API Key it is automatically created using the latest non-Beta API Version available.
You can specify a particular API Version for your new API Key by including the field apiVersion in your request body. See the Create API Key endpoint in the API Key docs for more info. Navigate to API Versions Changes to see currently available versions.
Generally speaking you should not specify an API Version when creating a new key. It is best practice to use the latest, non-beta version. This is because you should develop your application using the latest versions of the API.
If your application is already built and using a particular version of the API (i.e., you are just generating a new API key for a pre-existing application), then you should specify an API Version.
To upgrade an API Key's api version you can use the Update API Key endpoint in the API Key docs.
For example, to upgrade your API key to version 2024-05-22 in the sandbox environment you could run the command:
curl -i -X PUT \
'https://sandboxapi.peach.finance/api/keys/{$KEY_ID}' \
-H "X-API-Key: $YOUR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"apiVersion": "2024-05-22"
}'Downgrading your API Key api version is not allowed. You can only update an API Key to use a more recent API Version.
Similarly, when creating a new API Key, you cannot create one with an API Version older than the oldest one that already exists for your company.
The one exception to the "no downgrades" restriction is that—after upgrading an API Version—you have seven days in which you are permitted to downgrade that API Key.
Before updating your API Key you should test your application to ensure it works with the new version.
It is recommended you test first in the Sandbox environment. (Both Sandbox and Prod environments have the same versions)
- Using Versions — How to specify a version in your requests once you have a key.
- How to Upgrade — The procedure for moving an API key to a newer API version.