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.

https://connect.virginmoneygiving.com/vmgauthentication-web/vmgconnect/loginStartup.action?redirectSuccessURL={your callback URL if the call is successful}&redirectUnsuccessURL={your target URL if the call is unsuccessful}&api_key={your API key}

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

Example request:

https://connect.virginmoneygiving.com/vmgauthentication-web/vmgconnect/loginStartup.action?redirectSuccessURL=https://www.yourApplicationURL.com/api/vmg/successfulAuthorisation.do&redirectUnsuccessURL=https://www.yourApplicationURL.com/api/vmg/failedAuthorisation.do&api_key=jpa2v42yzjxrzmknn8z4e2ku&emailAddress=john.smith@virginmoneygiving.com&dateOfBirth=19611011

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:

https://www.YourApplicationUrl.com/api/vmg/successfulAuthorisation.do?authorisationCodeValue=u83dwtgnadvs2rp8ss9jffmj&authorisationCodeContext=04bbcb26-8d5f-11e2-ad62-005056a8589d&FundraiserResourceId=04bbcb26-8d5f-11e2-ad62-005056a8589d

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:

https://www.YourApplicationUrl.com/api/vmg/failedAuthorisation.do?errorMessage=The%2520fundraiser%2520declined%2520to%2520authenticate%2520the%2520OAuth%2520request

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:

Authorization: Bearer zrvaet8kc6wkwt4t27snq38b

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.