Interactive Login - API endpoint

Overview and limitations

The API login endpoint is the simplest method of integration for most applications in terms of development time expected to be required, but comes at the cost of being less flexible to edge cases than the embedded Betfair embedded login page. It will allow a user to provide a username and password or a username and (password + 2 factor auth code) if they have strong authentication enabled. Customers who writing bots are strongly recommended to use the non-interactive endpoint with an SSL certificate. We recommend that 3rd party applications which will be exposed to a wide range of users use the Interactive login method of embedding the Betfair embedded login page as this will allow your application to handle additional workflows, such as terms and conditions updates as well as additional jurisdictional specific identifiers.

Endpoint

Certificate Endpoint

https://identitysso.betfair.com/api/login

The presence of the "Accept: application/json" will signal SSO that it should responde with JSON and not with a HTML page.

Parameters (POST)

Name	Description	Sample
username (mandatory)	the username to be used for the login
password (mandatory)	the password to be used for the login	password03

Headers

Name	Description	Sample
Accept (mandatory)	header that signals that the response should be returned as JSON	application/json
X-Application (mandatory)	header the AppKey used by the customer to identify the product.	poker

Response structure

{
  "token":"<token_passed_as_header>",
  "product":"product_passed_as_header",
  "status":"<status>",
  "error":"<error>"
}

Status values

SUCCESS
LIMITED_ACCESS
LOGIN_RESTRICTED
FAIL

Error values (mappings for statuses to possible error values LIMITED_ACCESS / LOGIN_RESTRICTED / FAIL)

Business error codes:

LIMITED_ACCESS - Access is limited (eg. accounts that can login but can't bet), product session will be provided:

{
  "token": product_token,
  "product": product,
  "status": LIMITED_ACCESS,
  "error": error
}
 
error = {PENDING_AUTH | SECURITY_QUESTION_WRONG_3X | KYC_SUSPEND | SUSPENDED}

LOGIN_RESTRICTED - Login is restricted (in case of indirection point this is what will be returned), product session will not be provided:

{
  "token": "",
  "product": product,
  "status": LOGIN_RESTRICTED,
  "error": error
}
 
error = {STRONG_AUTH_CODE_REQUIRED | DENMARK_MIGRATION_REQUIRED | DANISH_AUTHORIZATION_REQUIRED | SPAIN_MIGRATION_REQUIRED | SPANISH_TERMS_ACCEPTANCE_REQUIRED | ITALY_MIGRATION_REQUIRED | ITALIAN_CONTRACT_ACCEPTANCE_REQUIRED | CHANGE_PASSWORD_REQUIRED | PERSONAL_MESSAGE_REQUIRED}

FAIL - All other cases are treeted as errors, product session will not be provided:

{
  "token": "",
  "product": product,
  "status": FAIL,
  "error": error
}
 
error = {TRADING_MASTER | TRADING_MASTER_SUSPENDED | AGENT_CLIENT_MASTER | AGENT_CLIENT_MASTER_SUSPENDED | DENMARK_MIGRATION_REQUIRED | INVALID_PIN | INVALID_USERNAME_OR_PASSWORD | PIN_DELETED_ON_FAILED_COUNT_EXCEEDED | UNRECOGNIZED_DEVICE | DUPLICATE_CARDS | ACCOUNT_NOW_LOCKED | ACCOUNT_ALREADY_LOCKED | SECURITY_RESTRICTED_LOCATION | BETTING_RESTRICTED_LOCATION | INVALID_CONNECTIVITY_TO_REGULATOR | INVALID_CONNECTIVITY_TO_REGULATOR | INVALID_CONNECTIVITY_TO_REGULATOR_IT | INVALID_CONNECTIVITY_TO_REGULATOR_DK| NOT_AUTHORIZED_BY_REGULATOR | NOT_AUTHORIZED_BY_REGULATOR | NOT_AUTHORIZED_BY_REGULATOR_DK | NOT_AUTHORIZED_BY_REGULATOR_IT | TELBET_TERMS_CONDITIONS_NA | CLOSED | SELF_EXCLUDED | NOT_AUTHORIZED_FOR_DOMAIN_ES | NOT_AUTHORIZED_FOR_DOMAIN_IT | NOT_AUTHORIZED_FOR_DOMAIN_COM | AUTHORIZED_ONLY_FOR_DOMAIN_ES}

Please note that master account access is restricted for API/JSON requests.

{
  "token": "",
  "product": "APP_KEY",
  "status": FAIL,
  "error": error
}
 
error = {INPUT_VALIDATION_ERROR | FORBIDDEN | INVALID_USERNAME_OR_PASSWORD | NO_SESSION | INVALID_PIN | INVALID_PIN_LOGIN_REQUEST | INVALID_PIN_LOGIN_REQUEST}

Curl call sample

curl -k -i -H "Accept: application/json" -H "X-Application: <AppKey>" -X POST -d 'username=<username>&password=<password>' https://identitysso.betfair.com/api/login

Example of a successful login:

curl -k -i -H "Accept: application/json" -H "X-Application: <AppKey>" -X POST -d 'username=<username>&password=<password>' https://identitysso.betfair.com/api/login
 
{
  "token":"SESSION_TOKEN",
  "product":"APP_KEY",
  "status":"SUCCESS",
  "error":""
}