Authentication is where everything starts, so choosing the proper authentication workflow is critical to your app's connection to SportsEngine. SportsEngine leverages multiple OAuth 2.0 flows such as PKCE, Hybrid, Client Credentials, and Resource Owner Authorization. If you are unfamiliar with OAuth workflows, we strongly recommend reading Okta auth0 at https://auth0.com/docs/get-started/authentication-and-authorization-flow.
If your application needs to continuously access organization data (e.g., teams, events, profiles), leverage the Client Credentials workflow. If your application acts on behalf of a user or uses SportsEngine as an SSO provider, leverage a user workflow such as PKCE, Hybrid, or Resource Owner.
Client ID & Client Secret
Each application accessing the SportsEngine platform is assigned a unique Client ID and Client Secret. Your application will always have a single Client ID regardless of how many organizations or users are accessible. To begin the review process and receive a Client ID and Secret, visit the link HERE.
While your Client ID will be part of authorization URLs, it is essential NEVER to expose your Client Secret. If your Client Secret is ever compromised, please contact support to reset your secret.
Setting up Client Redirects
Redirect URIs MUST be registered with SportsEngine for your application. The user will receive an error message immediately if your redirect is not registered. Multiple Redirect URIs can be configured for your Client ID to accommodate various environments like development, staging, pre-release, or production.
Client Credentials Authorization Workflow
This OAuth2 workflow is for server-to-server connections. The OAuth2 is the recommended workflow when your application needs to stay connected to SportsEngine, or you want to receive webhooks. The user granting permission to their data MUST be an organization administrator.
Step 1: Retrieve an access token
Make the following request to retrieve the access token for your Client ID.
The request header will now include the access token as a bearer token for all queries and mutations.
Request Body JSON
client_id: <CLIENT ID>
client_secret: <CLIENT SECRET>
grant_type: client_credentials
Response Body JSON
access_token: <ACCESS TOKEN>
token_type: bearer
expires_at: <EPOCH TIME>
expires_in: <MILLISECONDS>
Step 2: Build the authorization URL
An administrative user of the organization must grant access to their data for your application. Admins will redirect to log in when signed out of SportsEngine. Below is the link they will need to click from your application.
Query Parameters
client_id=<CLIENT ID>
redirect_uri=<REDIRECT URI>
scope=organization_grant
response_type=organization_grant
Step 3: Redirect to your application after approval
Once a user has logged in and approved data access, they will link to the Redirect URI with the organization ID in the "organization_grant" query parameter. You can then use the organization(id) query to verify access. To learn more, read our article Completing Your First GraphQL query.
User Authentication Workflow
This workflow focuses on interacting with SportsEngine on behalf of a user. Since this is a user-based authentication, your token will only be valid for the duration of the session. You must refresh the token or get a new token for each session.
Step 1: Build your Authorization URL
Construct a link to SportsEngine that your users will click to begin the process. It is comprised of your Client ID and Redirect URI.
Query Parameters
client_id=<CLIENT ID>
redirect_uri=<REDIRECT URI>
response_type=code
Step 2: Redirect to your application after login
If login is successful and the connection is approved, the user's browser will return to the Redirect URI you specified in Step 1. It will contain a "code" as a query parameter that you will need for Step 3.
Step 3: Retrieve your access token
It is important to note that the code in Step 2 has a 30-second lifespan. The flow must restart if this step is not requested before the authorization code expires. We place this time restriction to minimize security risks to sensitive data.
Request Body JSON
client_id: <CLIENT ID>
client_secret: <CLIENT SECRET>
code: <AUTH CODE>
grant_type: authorization_code
Step 4: Test your access token
The response will contain your access token. All data requests must contain this access token as a bearer token in the header.
Request Header
Authorization=Bearer <ACCESS TOKEN>
Step 5: Get a refresh token
Verify your token expiration time. A refresh token is present in the token response to maintain access and eliminate the need to go through the Authorization flow often.
Query Parameters
client_id=<CLIENT ID>
client_secret_uri=<CLIENT SECRET>
grant_type=refresh
Disconnecting Access
Organizations can view who approved a connection and when it was connected. They can also disconnect your application at any time. If you leverage user-based authentication and remove application access, the access token will no longer be valid. If you use client-based authentication, the organization will no longer appear in the organization's () query, and webhooks will no longer send.