Authentication is the first step in connecting your application to SportsEngine. Choosing the correct workflow ensures secure and reliable access to organizational data.

Preferred Method: User Authentication (acting on behalf of an organization admin).
SportsEngine supports multiple OAuth 2.0 flows, including PKCE, Hybrid, Client Credentials, and Resource Owner Password. If you are new to OAuth, we recommend reviewing Auth0’s guide on Authentication and Authorization Flows.

Authentication Options

User Authentication (Preferred)

Use when your app acts on behalf of an organization admin (e.g., pulling rosters, schedules, or profiles as if through the UI).

Organization Authorization

Use for server-to-server applications that require continuous access to organizational data. SportsEngine has added a custom grant type to our OAuth 2.0 implementation, allowing organization connections to persist beyond specific users.

Choosing the Right Workflow

Use Case	Workflow	Notes
App acts on behalf of an organization admin (rosters, schedules, profiles)	User Authentication (Preferred)	User logs in; token tied to session; refresh token supported
SportsEngine as an SSO provider for external apps	User Authentication	Standard OAuth 2.0 login flow
Server-to-server access that must persist (e.g., webhooks, cross-org data)	Organization Authorization	Requires org admin approval; token persists beyond user session
App needs continuous background access to an org’s data	Organization Authorization	Good for automated syncs, imports, and exports

Application Credentials

Every application receives a Client ID and Client Secret.

Client ID: Used in authorization URLs and requests.
Client Secret: Must be kept secure. If compromised, contact SportsEngine Support immediately.

Request credentials via API Settings in your SportsEngine account.

Redirect URIs

Redirect URIs must be registered with SportsEngine.

Unregistered URIs will fail immediately.
Multiple URIs can be configured (dev, staging, production).

User Authentication Flow (Preferred)

Build Authorization URL
- The user must be linked to the following URL:
```
GET https://user.sportsengine.com/oauth/authorize
```
  Parameters:
  - client_id=<CLIENT_ID>
  - redirect_uri=<REDIRECT_URI>
  - response_type=code
User Login + Redirect
- After successful login, the user is redirected to your redirect_uri with a code.

Exchange Code for Token

Use the code in the following request to exchange for an ACCESS_TOKEN and REFRESH_TOKEN. The code expires in 30 seconds.

POST https://user.sportsengine.com/oauth/token 
Content-Type: application/json

{  
 "client_id": "<CLIENT_ID>",
 "client_secret": "<CLIENT_SECRET>",
 "code": "<AUTH_CODE>",  
 "grant_type": "authorization_code" 
}

Response:

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "bearer",
    "expires_at": 1699999999,
    "expires_in": 1800,
    "refresh_token": "<REFRESH_TOKEN>"
}

Use Access Token
- The provided ACCESS_TOKEN should be included in the Authorization header of the requests made to the GraphQL API. To learn more, read our article Completing Your First GraphQL query.
- Use the following endpoint to inspect the granted credentials:
```
GET https://user.sportsengine.com/oauth/me
Authorization: Bearer <ACCESS_TOKEN>
```

Refresh Token

When the ACCESS_TOKEN expires, use the REFRESH_TOKEN to request a new one.

POST https://user.sportsengine.com/oauth/token
Content-Type: application/json

{
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>",
  "grant_type": "refresh_token",
  "refresh_token": "<REFRESH_TOKEN>"
}

Organization Authorization Flow

Use when apps integrate across multiple organizations.

Requires org admin approval.
Best for partner apps and webhook-driven integrations.

Authorization URL
- An organization administrator must grant permission. Link them to the following URL:
```
GET https://user.sportsengine.com/oauth/authorize
```
- Parameters:
  - client_id=<CLIENT_ID>
  - redirect_uri=<REDIRECT_URI>
  - scope=organization_grant
  - response_type=organization_grant
- Once the admin has logged in and approved data access, they will be redirected to your redirect_uri with the approved organization’s ID in the organization_grant query parameter.

Retrieve Access Token

POST https://user.sportsengine.com/oauth/token
Content-Type: application/json

{
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>",
  "grant_type": "client_credentials"
}

Response:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "bearer",
  "expires_at": 1699999999,
  "expires_in": 3600000
}

Redirect and Verify
- Use the retrieved ACCESS_TOKEN to query data from all organizations that have authorized the application.
- Use the organization(id) query to confirm. To learn more, read our article Completing Your First GraphQL query

NOTE: URL Authorization only needs to be done once for every organization.

Error Handling

Possible issues to expect:

Error	Cause	Resolution
invalid_client	Client ID/Secret mismatch	Verify credentials in API Settings
invalid_redirect_uri	Redirect not registered	Register redirect in API Settings
invalid_grant	Auth code expired (30s)	Restart flow
invalid_scope	Requesting unapproved scope	Request additional scopes
unauthorized_client	Client not allowed for workflow	Confirm correct workflow (User vs Organization)

Helpful tip! Always log error responses with timestamps for debugging.

Security Best Practices

Never expose your Client Secret in client-side code or logs.
Rotate credentials periodically and immediately after compromise.
Use HTTPS for all requests.
Limit scopes to the minimum required.
Store refresh tokens securely (encrypted at rest).
Audit connections regularly — org admins can revoke access at any time.

Disconnecting Access

Organizations can view and revoke connections at any time.
If revoked:
- User-based tokens → immediately invalid.
- Client credentials → org disappears from organization() query, webhooks stop.

Getting Started with API

Authenticating with SportsEngine