New API Version - 2015-04-29

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.

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).

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_code field on bank accounts with the more generic branch_code.

1. Generate an access token in the dashboard and update your authorisation header:

   Authorization: Bearer TOKEN

2. Update your version header:

   GoCardless-Version: 2015-04-29

3. Stop using the sort_code key in bank account creation calls, and instead use branch_code.

The use of users, roles, api_key and 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

Permissions in the new API version are replaced by scopes. There are two possible scopes: full_access and read_only.

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 read_only access.

Please take a moment to check your dashboard and ensure you're happy with your users’ scopes.

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

Webhooks

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.

Most integrations will already be using the branch_code field as it has been the documented interface since December.