Authentication

Authentication

A fundraising page is a protected resource, owned by the fundraiser. The fundraiser must grant you permission to create a page on their behalf. This permission is in the form of an access token that is required for the create fundraising page API call.

We use the OAuth 2.0 protocol to authenticate fundraisers where access is required to a protected resource. We've made it simple for you with the steps below.

If you're creating a new fundraising account, then the access token is provided automatically as part of the response for a successful create fundraiser account API call. You can then jump straight to step 3 below.

If the fundraiser already has a VMG account or you have an access token that has expired, your fundraiser must authorise you before you can create a page. The fundraiser will do this by signing in to their VMG account and confirming they are happy for a page to be created on their behalf.

Step 1 - Fundraiser signs in to VMG

To allow the fundraiser to sign in and grant you authorisation, you must redirect the fundraiser to our authentication application via the URL below. You can either open the authentication application in a pop-up window, or perform a browser redirect in the current window.

The implementation of how you invoke the authentication application is at your discretion. You should also formalise a mechanism to manage the response back, as well as pop-up window closure etc as applicable.

If you already know your fundraiser's email address, you can pass this as an additional parameter. This will pre-populate the authorisation form.

Parameter Required Data type Description
redirectSuccessURL True Varchar(100) This is the URL action that the authentication application will return to with the authorisation code and other details (see below) if the fundraiser successfully signs in and authorises you to create a page on their behalf. This must be secure (i.e. https) and must have been registered as the callback URL for your application. e.g. https://www.yourApplicationURL.com/api/vmg/successfulAuthorisation.do
redirectUnsuccessURL True Varchar(100) This is the URL action that the authentication application will return to if the fundraiser is unable to sign in or decides against authorising you to create a page on their behalf. E.g. https://www.yourApplicationURL.com/api/vmg/failedAuthorisation.do
api_key True Varchar(24) This is your key that allows you access to the VMG APIs.
shared_secret False Varchar(100) This is an optional password/shared secret that may have been generated when you registered your application.
emailAddress False Varchar(100) The fundraiser's email address associated with their VMG account.
dateOfBirth False Varchar(8) The fundraiser's date of birth in the format yyymmdd.

Example request:

If the fundraiser successfully signs in and agrees to let you create a page on their behalf you will be provided with their unique resource ID and an authorisation code in the response as URL parameters to the 'redirectSuccessURL'.

Example response:

The parameters 'authorisationCodeContext' and 'FundraiserResourceId' are the API reference of the fundraiser. The authorisation code is tied to this code context.

If the call is unsuccessful, then the response back looks like:

Step 2 - Exchange the authorisation code for an access token

Once you have an authorisation code, you have to exchange it for an access token using the following details:

Method: POST

URL: https://api.virginmoneygiving.com/token

Header Parameters:

  • Accept: application/json
  • Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
  • charset: utf-8
  • Content-Type: application/x-www-form-urlencoded

Content to send:

client_id={your API key}&redirect_uri={your callback URL}&code={authorisation code}&grant_type=authorization_code

 

Please note: the reponse from the above URL will always be in JSON format.

If successful, the access token is returned in the JSON response (see below) and you can then make the call to create the page (step 3).

{"token_type":"bearer","mapi":"[Your API Key]", "access_token":"kuquet6tf8capv5edjv49x3d","expires_in":1500}

If your call is unsuccessful, the JSON response looks like:

{"error":"invalid_grant","error_description":"Authorization code is invalid"}

 

Step 3 - Call create fundraising page API with an access token

You're almost there. The final step is to call the create fundraising page API, with the access token provided as a header parameter:

  • Parameter name: Authorization
  • Parameter value: Bearer {access token}

Example:

That's it. You should now have a brand new page for your fundraiser.

Please note: the access token is valid only for a short while and if not used within that period, will expire. You will then need the fundraiser to grant you access again by repeating the process from Step 1.