Authentication Information
All RegattaCentral API applications require authentication.
- Standard API users: If you are using the API 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".
Note: Generation of API credentials is currently limited to key clients and partners.
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":"[email protected]",
"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