New API Version - 2015-04-29
By Pete HamiltonApr 20153 min read
We last released a new version of the GoCardless Pro API back in November. Since then we’ve made countless improvements and recently we've been working on several new features which warrant the release of a new version.
2015-04-29 is being released on Wednesday, along with a corresponding update to our dashboards. For the majority of integrations, the upgrade will be extremely simple (see upgrading).
The new API docs are available at: https://developer.gocardless.com/pro/2015-04-29/
We will continue our support for v2014-11-03 until the 1st of July, 2015.
Summary of changes
Simplifies authentication and permissions by moving to OAuth2
- The API now uses token based Authentication.
- Api Keys and Publishable Api Keys have been replaced with Access Tokens and Publishable Access Tokens respectively.
- Removes Users and Roles from the API (user permissions can still be managed using the dashboard).
- Replaces the UK-specific
sort_codefield on bank accounts with the more generic
Generate an access token in the dashboard and update your authorisation header:
Authorization: Bearer TOKEN
Update your version header:
- Stop using the
sort_codekey in bank account creation calls, and instead use
The use of
publishable_api_key endpoints was extremely low and in most cases integrators made no use of these endpoints. However, if you do make use these in your integration and are unsure how to proceed, please don’t hesitate to get in touch.
Full details of the changes### API Authorisation
Permissions in the new API version are replaced by scopes. There are two possible scopes:
We've assigned scopes to your users based on their previous permissions. If a user had full access to any resources before, they have been assigned
full_access, otherwise they've been given
Please take a moment to check your dashboard and ensure you're happy with your users’ scopes.### API Authentication
To support future improvements we're switching API authentication from HTTP Basic to OAuth2.
In the future this will allow us to support partner application use cases, enabling you to authorize applications to perform actions on your behalf. It also simplifies our API authentication strategy (one token, as opposed to two components with base 64 encoding).
To authenticate with the new API version, you will need to modify your authorisation header (docs):
# Old Authorization: Basic BASE64_ENCODED_CREDS # New Authorization: Bearer TOKEN
You can continue to manage API Keys and Publishable API Keys in the API using
v2014-11-03, but they won't appear on your dashboard any more. For migration instructions, please see the upgrade guide
We’ve moved the concept of webhook endpoints to their own section of the dashboard and changed the detail used to sign them: going forward, webhook endpoints have a “secret”, which is used to sign requests (docs).
For existing integrations, we've copied across webhook details from API Keys and set the secret to be the API Key's
key. As a result, no changes to existing integrations are required unless you rely on the
Webhook-Key-Id header, which has been removed.
### Farewell Sort Codes, Long Live Branch Codes! Since we now support [local details](https://developer.gocardless.com/pro/#ui-compliance-local-bank-details) for [all the countries](https://developer.gocardless.com/pro/#overview-supported-direct-debit-schemes) you can collect payments from, we've replaced the UK-specific `sort_code` field on bank accounts and bank account tokens with the generic `branch_code` field.
Most integrations will already be using the
branch_code field as it has been the documented interface since December.