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, complete the form below. You must have a valid RegattaCentral account to obtain credentials for the API. Using a "client secret" that you provide, along with your RegattaCentral username and password, and a description of the app you are creating, your assigned "API-key" and "client-id" will be displayed.

This is a BETA release of the API V4.0. When this version is officially released, all existing authorization keys and clients will be revoked. To obtain new credentials every API user will be required to agree to the RegattaCentral API License Agreement.

CORS (Cross Origin Resource Sharing) is allowed but is restricted to the domain that you specify when you obtain your credentials. If you specify a referer then requests made to the RegattaCentral API using your API-Key or Client-Id generated token must have a HTTP Origin header that matches. Only secure origins are allowed, so your referer must begin with ""HTTPS://".

You may update the client description or referer by entering your RegattaCentral username and password and your existing client secret, along with the updated description or referer. If you specify a different client secret, and/or different RegattaCentral credentials, you will be issued a new API-Key and a new client-id.

You may also request a list of your currently assigned credentials here.

If you forget or wish to change your client-secret or API-Key or if you wish to disable your credentials, please contact RegattaCentral Support or email api@regattacentral.com

Request Credentials

An API-Key and Client ID must be obtained once for each application which utilizes the RegattaCentral API. Use your RegattaCentral account and a "client secret" to create your credentials. The API-Key can be used to access basic regatta information and the Client-Id and Client-secret can then be used by you or your users to create an authorization token (see Request Token).

Only 1 client id will be created for any given username/client_secret pair. Attempts to use the same username and client_secret will result in the existing client-id being returned. If you need multiple client-ids, then you must specify a different username and/or client_secret.

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

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