Authentication Information

All RegattaCentral API applications require authentication.

  • Standard API users: If you are using the API to for displaying general information about regattas, including events, entries and results, you may specify an API key in the request header. Use of this key does not require that your application users to log in, thus allowing any user access to general regatta information. Users must supply this as a request header using the key "API-Key".
  • Authenticated API users: Applications which require detailed information about a regatta and/or will be posting data to RegattaCentral are required to use the industry standard OAuth2 protocol to provide authenticated authorization. Your application will need to prompt the user for their RegattaCentral credentials, then using your assigned client credentials, request that an OAuth2 token be issued. Your application will then need to specify this token in the request header using the key "Authorization".

    To access a specific regatta, the RegattaCentral user account that was used to obtain the OAuth2 token will be validated as having "staff" access to the regatta. Therefore it is possible to have a valid OAuth2 token, yet receive an HTTP status 401 "Unauthorized" response. Users must be authorized by the regatta director before using their account to access a regatta.

    A valid OAuth2 token may be utilized for obtaining general information by supplying it with the HTTP header "Authorization".

To obtain an API key and client credentials, email api@regattacentral.com and include your RegattaCentral username and a brief description of how you intend to use the API.

Show Credentials

Use this form to display the API credentials that you have previous created for your RegattaCentral account. This is supplied here for your convenience and should not be used in your application.

Your client_id, client_secret, username and password must always be kept secure and not shared with anybody nor exposed over the Internet.

Results: JSON

Request Token

This service must be called prior to all authenticated calls in order to retrieve an authorization token. This authorization token can then be passed as an Authorization header to all authenticated calls. The results also includes a expiration time for the authorization token. A refresh token is also included in case the authorization token expires prior to the finishing the use of the API, the refresh token can be used to obtain a new authorization token (see Refresh Token).

URL: https://api.regattacentral.com/oauth2/api/token

POST body

client_id={Client_id}&client_secret={Client_secret}&username={Username}&password={Password}&grant_type=password

Client_id
An application specific id that must be obtained from RegattaCentral.

Client_secret
An application specific secret that must be obtained from RegattaCentral.

Username
Valid RegattaCentral username.

Password
Password associated with the RegattaCentral username.

Response

{
  "access_token":"8ce2bba001c2d6153cb04e4a2ffa1ca3"
  "expires_in":3600,
  "refresh_token":"f7d338c11a68cf55b804eda19776eadc",
}                                  

access_token
The authorization token that must be passed in the Authorization header for all authenticated calls.

expires_in
Number of seconds before access_token expires.

refresh_token
A token that can be used to get a new access_token when the current token expires (see Refresh Token).

Data:

Code: JavaScript + jQuery

$.ajax({
    type: "POST",
    url: 'https://api.regattacentral.com/oauth2/api/token',
    data: 'client_id={client_id}&client_secret={client_secret}&username={username}&password={password}&grant_type=password',
    success: function (data) {
        // Process & Display Data
    },
    error: function () {
        alert('Error processing request.');
    }
});

Code: PHP

function callHttps() {
	$postData = array(
    	'client_id' => '{client_id}',
    	'client_secret' => '{client_secret}',
    	'username' => '{username}',
    	'password' => '{password}',
		'grant_type' => 'password'
	);
	// Create the context for the request
	$context = stream_context_create(array(
    	'http' => array(
	    	'method' => 'POST',
       		'header' => "Accept: application/json\r\n"."Content-Type: application/x-www-form-urlencoded\r\n",
        	'content' => http_build_query($postData)
    	)
	));
	// Send the request
	$response = file_get_contents('https://api.regattacentral.com/oauth2/api/token', FALSE, $context);

	// Check for errors
	if($response === FALSE){
		die('Error');
	}
	// Decode the response
	$responseData = json_decode($response, TRUE);

	// Print the date from the response	
	echo 'Token: '.$responseData['access_token'].'\r\n';
	echo 'Refresh Token: '.$responseData['refresh_token'].'\r\n';
	echo 'Expiration: '.$responseData['expiration'].'\r\n';
}

Results: JSON

Refresh Token

This service may be called to retrieve a new token based on the refresh token. This allows you to re-authenticate without having to prompt and pass the username and password.

URL: https://api.regattacentral.com/oauth2/api/token

POST body

client_id={Client_id}&client_secret={Client_secret}&refresh_token={Refresh_token}&grant_type=refresh_token

Client_id
An application specific id that must be obtained from RegattaCentral.

Client_secret
An application specific secret that must be obtained from RegattaCentral.

Refresh_token
The refresh_token that was issued with the original token request.

Response

{
  "expires_in":3600,
  "access_token":"962bd83b5b2ed047e0c1413f0b7a019d"
}                                  

access_token
The new authorization token that must be passed in the Authorization header for all authenticated calls.

expires_in
Number of seconds before access_token expires.

Data:

Code: JavaScript + jQuery

$.ajax({
    type: "POST",
    url: 'https://api.regattacentral.com/oauth2/api/token',
    data: 'client_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}&grant_type=refresh_token',
    success: function (data) {
        // Process & Display Data
    },
    error: function () {
        alert('Error processing request.');
    }
});

Results: JSON

Validate Token

This service may be used to verify that a token is still valid.

URL: https://api.regattacentral.com/oauth2/api/validate

POST body

token={Token}

Token
A previously generated token generated by the RegattaCentral OAuth process.

Response

{
  "username":"regattacentral@juddsolutions.com",
  "access_token":"8ce2bba001c2d6153cb04e4a2ffa1ca3"
}                                  

access_token
The authorization token that was verified.

username
The username that was used to create the token.

Data:

Code: JavaScript + jQuery

$.ajax({
    type: "POST",
    url: 'https://api.regattacentral.com/oauth2/api/validate',
    data: 'token={token}',
    success: function (data) {
        // Process & Display Data
    },
    error: function () {
        alert('Error processing request.');
    }
});

Results: JSON

RegattaCentral © 2018 | Support | Privacy

RegattaCentral © 2018 | Support | Privacy