...
Table of Content Zone | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
When & How to Use Vendor ServicesThere are two separate methods available to Vendors.
The Vendor Services API allows licensed and certified Software Vendors to manage the permissioning of Betfair accounts to their API-NG application/s. With the Vendor Services API, you can:
There are two key processes that Vendor will need to following when using the Vendor Services in API-NG: Each of these processes are detailed below.
Preconditions:
Example flow:
Anchor |
|
Anchor | ||||
---|---|---|---|---|
|
The Vendor Web API is available to licensed Software Vendors who are creating web based applications These operations enable the web application to carry out operations on the users behalf using the OAuth2 protocol.
Operations
The following operations are available via the Vendor Web API
OAuth 2 Flow - Creating an Access Token
The user authentication via web apps is underpinned by the OAuth 2 protocol.
You will need to redirect the user to the Betfair login page (identitysso.betfair.com/view/vendor-login), along with up to three parameters:
- client_id (mandatory): this is your vendor ID, returned to you by the getDeveloperAppKeys call provided you have been registered as a web vendor
- response_type: this needs to be set to 'code', to indicate you are requesting an authorization code (see later)
- redirect_uri (optional): this will be appended to the URL you provided upon sign up to the Vendor Program when we redirect the user back to your site after login. This needs to be URL encoded.
Code Block | ||
---|---|---|
| ||
https://identitysso.betfair.com/view/vendor-login?client_id=123456&response_type=code&redirect_uri=newjoiner |
Note | ||
---|---|---|
| ||
If you're a Betfair Affiliate, you should append the following to the redirect_uri to ensure that any new account sign ups are linked to your assigned partnerId '&rfr=xxxx&PI=xxxx&pi=partnerxxxx' Please replace 'xxxx' with your own partnerId For example: https://identitysso.betfair.com/view/vendor-login?client_id=123456&response_type=code&redirect_uri=newjoiner&rfr=12345&PI=12345&pi=partner12345 |
The user will log in and be presented with a message asking them to allow you to perform Betfair calls on their behalf, as shown below.
Info |
---|
Should they accept this message, they will be redirected to your site (using your redirect URL + any optional parameters). Critically, we will include an authorization code as a parameter, under the parameter name "code". NOTE: The authorization code will be valid for a single use for 10 minutes. |
Code Block | ||
---|---|---|
| ||
https://mywebsite.com/newjoiner?code=12345 |
Info |
---|
You will need to propagate this 'code' to your back-end, from which you will have to exchange it for an access token. The access token will allow you to use the Betfair API on the user's behalf. To obtain the access token you will need to call the token operation on the Accounts API |
Example Token Request
The token call takes the following parameters:
Request Headers
- Header: 'X-Application' : 'your app key'
- Header: 'X-Authentication' : 'your session token'
Request Body
- client_id: your vendor ID, returned to you by the getDeveloperAppKeys call provided you have been registered as a web vendor
- grant_type: in this context, this will have to be set to 'AUTHORIZATION_CODE'
- code: the code you were returned
- client_secret: your secret, obtained from GetDeveloperAppKeys
Response Parameters
- access_token: the access token, used to call Betfair on the user's behalf
- token_type: meta data for the access token (see 'Making calls on the user's behalf')
- expires_in: how long the access token will be valid for (in seconds)
- refresh_token: a token that can be used to create a new access token (see 'Using the refresh token')
- application_subscription: contains the vendor client ID, a unique identifier for a user. Can also contain some subscription related information (See 'Legacy Subscriptions')
Warning | ||
---|---|---|
| ||
To protect sensitive information such as your app key and secret, it is important that the token operation only be called from server to server. |
Code Block | ||
---|---|---|
| ||
X-Application: 'your App key' X-Authentication : 'your session token' Accept: application/json Content-Type: application/json Endpoint https://api.betfair.com/exchange/account/rest/v1.0/token/ Request Body {"client_id"="4534","grant_type":"AUTHORIZATION_CODE","code":"-22a1-12151008-000007cb61","client_secret":"bc183d-f5-40dc-82a6-d97681 Response {"access_token":"KeOi+kyg2RvDK4HM+W46CvSnP5w=","refresh_token":"50d76117-7f85-375v-a38f-ffb332713f93","application_subscription":{"vendor_client_id":"456238"},"token_type":"BEARER","expires_in":"14400"} |
Code Block | ||
---|---|---|
| ||
X-Application: 'your App key' X-Authentication : 'your session token' Accept: application/json Content-Type: application/json Endpoint https://api.betfair.com/exchange/account/json-rpc/v1 Request {"jsonrpc": "2.0", "method": "AccountAPING/v1.0/token", "params": {"client_id":"CLIENTID","grant_type":"AUTHORIZATION_CODE","code":"CODE","client_secret":"CLIENTSECRET"}, "id": 1 } |
OAuth 2 Flow - Using the Refresh Token
When the access token expires, it is possible to create a new one without any user input, using the refresh token. This is done with the same call that was used to create it originally, the token operation, but with a different set of parameters, for example, grant_type: REFRESH_TOKEN and refresh_token:
Header: 'X-Application' : 'your app key'
Header: 'X-Authentication' : 'your session token'
client_id: your vendor ID, obtained from /wiki/spaces/OL/pages/1671181
grant_type: 'REFRESH_TOKEN'
refresh_token: the refresh token for the user
client_secret: your secret, obtained from/wiki/spaces/OL/pages/1671181
This will return the same information as the original call:
access_token: the access token, used to call Betfair on the user's behalf
token_type: meta data for the access token (see 'Making calls on the user's behalf')
expires_in: how long the access token will be valid for (in seconds)
refresh_token: the refresh token remains the same
application_subscription: contains the vendor client ID, a unique identifier for a user
Code Block | ||
---|---|---|
| ||
https://api.betfair.com/exchange/account/rest/v1.0/token?client_id=VENDOR_ID&client_secret=VENDOR_SECRET&grant_type=REFRESH_TOKEN&refresh_token=50d76117-7f85-375v-a38f-ffb332713f93 |
Code Block | ||
---|---|---|
| ||
{"access_token":"KeOi+kyg2RvDK4HM+W46CvSnP5w=","refresh_token":"50d76117-7f85-375v-a38f-ffb332713f93","application_subscription":{"vendor_client_id":"456238"},"token_type":"BEARER","expires_in":"14400"} |
Tip |
---|
You can user the 'expires_in' value to determine when the access token will stop being valid. Alternatively, if calls made with the access token start returning an INVALID_SESSION error, it is likely that the token has expired. |
Making API Calls On The Users Behalf
Once you have an access token, you can start calling the Betfair API on the user's behalf based on their actions on your site.
You will need to populate headers in a different way to a standard API call:
X-Application: your application key
Authorization: token_type + " " + access_token
The Authorization header needs to be a concatenation of the token type and the access token (both returned by the token call), separated by a space.
Example:
Betfair will use the access token to determine which user the calls are being made for.
These calls also have to be from back-end to back-end.
Note | ||
---|---|---|
| ||
The following API operations aren't available using the Vendor Web API
|
User Revocation
The user may choose to revoke the permissions previously granted to your web application. This will invalidate the access token and destroy your refresh token. Any subsequent calls to Betfair using the access token, or any attempt to generate a new one using the refresh token will result in either an INVALID_SESSION exception or UNEXPECTED_ERROR respectively.
Legacy Subscriptions
The way subscriptions are handled for web applications differ greatly from the way they were for desktop based applications. The subscription token model is no longer enforced, however you may still choose to create and manage subscriptions using the existing API calls.
Please note that in this model, Betfair will no-longer prevent requests for a user with an expired or cancelled subscription. You can choose what action to take based on information contained in the application_subscription field returned by the token operation.
The available operations are the following:
- getApplicationSubscriptionToken
- activateApplicationSubscription
- cancelApplicationSubscription
- updateApplicationSubscription
- listApplicationSubscriptionTokens
- getApplicationSubscriptionHistory
If you do use these calls to manage subscriptions, the token call will return information on the most relevant subscription (i.e. the subscription with the latest expiration date) as part of the application_subscription object.
Flow Diagram
Sample Code
Sample code that demonstrates the web apps interaction is available via https://github.com/betfair/sample-web-app-vendor/
...