- Previous: Charity details
- Up: Introduction
- Next: Useful information
Authentication
Page and account creation APIs are now unavailable so please consider your use of our APIs and how this affects you. All other APIs will be available until 18 February. If you have any questions please take a look at our Q&A.
Documentation
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.
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:
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.
- Previous: Charity details
- Up: Introduction
- Next: Useful information
Docs Navigation
- Introduction
- Getting started
- Fundraiser search
- Fundraiser details
- Fundraiser details V2
- Fundraising page details
- Fundraising page details V2
- Charity search
- Validate URL
- Country code lookup
- Address lookup
- Account Exists
- Create fundraiser account
- Activity lookup
- Event search
- Create fundraiser page
- Event summary
- Event fundraisers
- Event Fundraisers V2
- Event fundraisers 2
- Event fundraisers 2 V2
- Charity fundraisers
- Charity fundraisers V2
- Charity details
- Authentication
- Useful information
- Error codes
- Glossary
- Software development kit