{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"API Versioning with API keys","siteUrl":"https://docs.peachfinance.com","description":"API and product documentation for Peach Finance, a lending-as-a-service platform.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-versioning-with-api-keys","__idx":0},"children":["API Versioning with API keys"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An API Key is linked to an API Version."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To see the API version your API Key is using fetch your API keys with the Get API Keys endpoint ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/api-keys/"},"children":["see the API Keys doc"]}," and reference the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiVersion"]}," field."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Therefore, if you are using an API key in your application your application is effectively \"pinned\" to use a particular API Version."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-an-api-key-with-an-api-version","__idx":1},"children":["Creating an API key with an API version"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create an API Key it is automatically created using the latest non-Beta API Version available."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can specify a particular API Version for your new API Key by including the field ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiVersion"]}," in your request body. See the Create API Key endpoint in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/api-keys/"},"children":["API Key docs"]}," for more info. Navigate to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/breaking-changes"},"children":["API Versions Changes"]}," to see currently available versions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"upgrading-an-api-keys-api-version","__idx":2},"children":["Upgrading an API key's API version"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To upgrade an API Key's api version you can use the Update API Key endpoint in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/api-keys/"},"children":["API Key docs"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, to upgrade your API key to version ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2024-05-22"]}," in the sandbox environment you could run the command:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"curl -i -X PUT \\\n  'https://sandboxapi.peach.finance/api/keys/{$KEY_ID}' \\\n  -H \"X-API-Key: $YOUR_API_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"apiVersion\": \"2024-05-22\"\n  }'\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"no-downgrading","__idx":3},"children":["No downgrading"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Downgrading your API Key api version is not allowed. You can only update an API Key to use a more recent API Version."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"test-before-updating","__idx":4},"children":["Test before updating"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before updating your API Key you should test your application to ensure it works with the new version."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is recommended you test first in the Sandbox environment. (Both Sandbox and Prod environments have the same versions)"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":5},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/using-versions"},"children":["Using Versions"]}]}," — How to specify a version in your requests once you have a key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-tools/how-to-upgrade"},"children":["How to Upgrade"]}]}," — The procedure for moving an API key to a newer API version."]}]}]},"headings":[{"value":"API Versioning with API keys","id":"api-versioning-with-api-keys","depth":1},{"value":"Creating an API key with an API version","id":"creating-an-api-key-with-an-api-version","depth":2},{"value":"Upgrading an API key's API version","id":"upgrading-an-api-keys-api-version","depth":2},{"value":"No downgrading","id":"no-downgrading","depth":3},{"value":"Test before updating","id":"test-before-updating","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"API Versioning with API keys"}},"lastModified":"2026-05-01T14:33:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-tools/api-keys","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}