UTR Sports Engage API

The Engage API allows cross-platform users (aka users from 3rd party sites who are also UTRS members) to connect their accounts. Once their accounts are connected, 3rd party sites can hit endpoints hosted within our Engage API service to retrieve player ratings (more functionality is planned for the future but for now the service is focused on providing ratings data).

Prerequisites

To utilize the UTRS OAuth flow, you will need the following:

Client ID (provided by UTRS)
Client Secret (provided by UTRS)
Redirect URI (created by the client and communicated to UTRS)

Authentication

UTR Sports uses OAuth2 for authentication. OAuth allows external applications to request authorization to a user’s data. It allows users to grant and revoke API access on a per-application basis and keeps users’ authentication details safe.

All developers need to register their application before getting started. A registered application will be assigned a client ID and client secret. The secret is used for authentication and should never be shared.

Note that in order to view sample Curl requests and other examples, it’s best to refer to our Swagger documentation here:

https://prod-utr-engage-api-data-azapp.azurewebsites.net/swagger/index.html



When you access Swagger, simply login without a username or password entered as these documents are public.

OAuth Overview

When OAuth is initiated, the user is prompted by the application to log in or sign up (if the user is not yet already a member) on the UTR Sports website and to give consent to the requesting application. A user can opt out of the scopes requested by the application.

After the user accepts or rejects the authorization request, UTR Sports redirects the user to a URL specified by the application. If the user authorized the application, the URL query string will include an authorization code and the scope accepted by the user. Apps should check which scopes a user has accepted. Applications complete the authorization process by exchanging the authorization code for a refresh token and short-lived access token.

Access tokens are used by applications to obtain and modify UTR Sports resources on behalf of the authenticated player. Refresh tokens are used to obtain new access tokens when older ones expire.

Here is a high level overview of the OAuth flow:

Requesting Access

To initiate the flow, applications must redirect the user to UTR Sports’s authorization page. At the moment, OAuth is authorized on web via GET

Prod URL:

https://prod-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/authorize

Dev URL:

https://dev-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/authorize

Note that the URLs above require the params outlined in our Swagger docs. You can see a full example of a functioning URL in our sample test flows further down in the doc here.

Details About Requesting Access

The authorization page will prompt the user to grant your application access to their data. Scopes requested by the application are shown as checked boxes, but the user may opt out of any requested scopes. If an application relies on specific scopes to function properly, the application should make that clear before and after authentication.

client_id required integer, in query	The application’s ID, obtained during registration.
redirect_uri required string, in query	URL to which the user will be redirected after authentication. Must be within the callback domain specified by the application.
third_party_user_id required string, in query	Unique ID associated with the third party’s site.
approval_prompt string, in query	force or auto, use force to always show the authorization prompt even if the user has already authorized the current application, default is auto.
scopes required string, in query	Requested scopes, e.g. "ratings". Applications should request only the scopes required for the application to function normally.
state string, in query	Returned in the redirect URI. Useful if the authentication is done from various points in an app.

Token Exchange

UTR Sports will respond to the authorization request by redirecting the user agent to the redirect_uri provided.

If access is denied, error=access_denied will be included in the query string.

If access is accepted, code and scopes parameters will be included in the query string. The code parameter contains the authorization code required to complete the authentication process. code is short lived and can only be used once. The application must now call the POST with its client ID and client secret to exchange the authorization code for a refresh token and short-lived access token (see step 7 under Sample test flows Scenario 1 for instructions on how to correctly call this endpoint):

Prod URL:

https://prod-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/token

Dev URL:

https://dev-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/token

The state parameter will always be included in the response if it was initially provided by the application.

Request Parameters

client_id required integer, in query	The application’s ID, obtained during registration.
client_secret required string, in query	The application’s secret, obtained during registration.
code required string, in query	The code parameter obtained in the redirect.
grant_type required string, in query	The grant type for the request. For initial authentication, must always be "authorization_code".

A refresh token, access token, and access token expiration date will be issued upon successful authentication.

expires_at integer	The number of seconds since the epoch when the provided access token will expire
expires_in integer	Seconds until the short-lived access token will expire
access_token string	The access token for this user.
refresh_token string	The refresh token for this user, to be used to get the next access token for this user. Please expect that this value can change anytime you retrieve a new access token. Once a new refresh token code has been returned, the older code will no longer work.
player string	A summary of player information (for more details on this response, see the EngageApi.OAuth.TokenExchangeResponse object in Swagger)

Refreshing Expired Access Tokens

Access tokens expire six hours after they are created, so they must be refreshed in order for an application to maintain access to a user’s resources. Every time you get a new access token, we return a new refresh token as well. If you need to make a request, we recommend checking to see if the short-lived access token has expired. If it has expired, request a new short-lived access token with the last received refresh token.

To refresh an access token, applications should call the POST endpoints (specifying grant_type: refresh_token and including the application’s refresh token for the user as an additional parameter):

https://prod-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/token

https://dev-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/token

If the application has an access token for the user that expires in more than one hour, the existing access token will be returned. If the application’s access tokens for the user are expired or will expire in one hour (3,600 seconds) or less, a new access token will be returned. In this case, both the newer and older access tokens can be used until they expire.

A refresh token is issued back to the application after all successful requests. The refresh token may or may not be the same refresh token used to make the request. Applications should persist the refresh token contained in the response, and always use the most recent refresh token for subsequent requests to obtain a new access token. Once a new refresh token is returned, the older refresh token is invalidated immediately.

Request Parameters

client_id required integer, in query	The application’s ID, obtained during registration.
client_secret required string, in query	The application’s secret, obtained during registration.
grant_type required string, in query	The grant type for the request. When refreshing an access token, must always be "refresh_token".
code required string, in query	The code parameter obtained in the redirect.

A few recommendations

Storing the scopes your players accept is great in case you get unexpected results (for example: why am I not getting activities for this user?).
In general, we recommend storing short-lived access tokens and refresh tokens in separate tables

Accessing the API Using an Access Token

Applications use unexpired access tokens to make resource requests to the UTR Sports API on the user’s behalf. Access tokens are required for all resource requests, and can be included by specifying the Authorization: Bearer #{access_token} header.

As of Summer 2024, clients may access our /api/v1/members/ratings endpoint via GET to retrieve rating information for cross-platform users:

Prod URL:

https://prod-utr-engage-api-data-azapp.azurewebsites.net/api/v1/members/ratings

Dev URL:

https://dev-utr-engage-api-data-azapp.azurewebsites.net/api/v1/members/ratings

See Swagger docs for information on the expected response. Note that, in the future, we plan to add additional endpoints that will serve other data, such as player biographical information.

Deauthorization

Applications can revoke access to a player's data. This will invalidate all refresh tokens and access tokens that the application has for the player. Access tokens are required for deauthorization requests, and can be included by specifying the Authorization: Bearer #{access_token} header. All requests made using invalidated tokens will receive a 401 Unauthorized response.

The POST endpoints are:

Prod URL:

https://prod-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/deauthorize

Dev URL:

https://dev-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/deauthorize

Request Parameters

scopes

required string, in query

The scopes to be deauthorized.

See Swagger docs for information on the expected response.

Rate Limits

Partners are limited to 1000 requests per minute across all API requests in a rolling window. Requests in excess of this rate limit will return an error response with a 429 status code.

Sample test flows

Scenario 1 - User already logged in

In this scenario, we’ll show how to recreate the flow of a user on a client site who’s also: 1) already logged into UTRS and 2) wants to connect that account with their client account.

User clicks connect on client site.

To simulate this step, use the following URL

Note that if you go back through the flow a second time, you will need to change approval_prompt=auto to approval_prompt=force (otherwise you will see a message like {"ReturnCode":"InvalidUsageOfApprovalPrompt"...).

Prod URL:

https://prod-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/authorize?client_id=abc123&redirect_uri=https://www.google.com&third_party_user_id=12345&approval_prompt=auto&scope=ratings

Dev URL:

https://dev-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/authorize?client_id=abc123&redirect_uri=https://www.google.com&third_party_user_id=12345&approval_prompt=auto&scope=ratings



User redirected to UTRS.
User confirms account to connect.
User confirms authentication.
User is redirected back to client site.

Redirection step includes authorization code (e.g. www.google.com/?code=def456…), which is used in subsequent steps.

From this point forward, the flow is entirely on the backend. To recreate these steps, please see our Swagger documentation to follow along.

Also please note that the following steps are time sensitive (authorization codes and access tokens expire after a set amount of time).

Using the authorization code provided in step 5, request and receive an access and refresh token via the /api/v1/oauth/token endpoint.

Sample POST request body here:

{

"client_id": "abc123",

"client_secret": "secret",

"code": "<authorization code retrieved from step 5>",

"grant_type": "authorization_code"

}



Using the access token received in the previous step, the client site may now send a GET request to the /api/v1/members/ratings endpoint to retrieve the user’s ratings.

Include the access token in the header with “Bearer <access-token-value>”.

Scenario 2 - User not logged in/switches account

In this scenario, the user comes from the client site and, when prompted, decides to either use a different account or signup for UTRS before moving on to the authorization step.

User clicks connect on client site.

To simulate this step, use the following URL:

Note that if you go back through the flow a second time, you will need to change approval_prompt=auto to approval_prompt=force (otherwise you will see a message like {"ReturnCode":"InvalidUsageOfApprovalPrompt"...).

Prod URL:

https://prod-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/authorize?client_id=abc123&redirect_uri=https://www.google.com&third_party_user_id=12345&approval_prompt=auto&scope=ratings

Dev URL:

https://dev-utr-engage-api-data-azapp.azurewebsites.net/api/v1/oauth/authorize?client_id=abc123&redirect_uri=https://www.google.com&third_party_user_id=12345&approval_prompt=auto&scope=ratings



User redirected to UTRS.
User decides to login with a different account or go through signup process.
User logs in and arrives at their UTRS home page.
User should now go back to the client site and follow the steps in Scenario 1 above.

What are you looking For?

UTR Sports Engage API

Table of Contents

Project Overview

Prerequisites

Authentication

OAuth Overview

Requesting Access

Details About Requesting Access

Token Exchange

Request Parameters

Refreshing Expired Access Tokens

Request Parameters

A few recommendations

Accessing the API Using an Access Token

Deauthorization

Request Parameters

Rate Limits

Sample test flows

Scenario 1 - User already logged in

Scenario 2 - User not logged in/switches account