OAuth 2.0

🔑 Grant Types

We support two OAuth 2.0 grant types for API authorization, each designed for different use cases:

1. Client Credentials (Server-to-Server)

The Client Credentials grant type is designed for server-to-server communication, where the API is accessed from a trusted backend rather than directly from a front-end application.

✅ Use Cases

The Client Credentials grant type is ideal for:

Backend services that need to interact with our API without user intervention
Automated processes, such as scheduled tasks or data synchronization
Creating a custom backend API that securely fetches data and exposes only what your front-end needs

❗️
Warning
Do not use these APIs directly from a front-end application. Exposing client credentials in a front-end environment poses a significant security risk.
Instead, create your own secure backend that communicates with our API and acts as a safe proxy for the front-end.

2. Authorization Code Flow with PKCE (User-Facing)

The Authorization Code Flow with PKCE (Proof Key for Code Exchange) is designed for user-facing applications, including single-page applications (SPAs), mobile apps, and other public clients that cannot securely store client secrets.

📘
Quick Tip:
Our Authorization Code Flow is OpenID Connect (OIDC) compliant.
You can load the OIDC configuration from https://auth.myzone.org/.well-known/openid-configuration

✅ Use Cases

The Authorization Code Flow with PKCE is ideal for:

Single-page applications (SPAs) built with React, Vue, Angular, etc.
Mobile applications (iOS, Android)
Desktop applications
Any public client that needs to authenticate users and access their data
Applications where users need to grant permission to access their account data

🔒
Security Benefits
PKCE prevents authorization code interception attacks and eliminates the need to store client secrets in public clients, making it much safer for front-end applications.

🔒 Scopes

OAuth 2.0 scopes define the level of access granted to an API client. Scopes allow you to control what category of endpoints your client can access and what actions it can perform.

📚 Available Scopes

Category	Scope
Accounts	`read:accounts`
	`write:accounts`
	`delete:accounts`
Moves	`read:moves`
Biometrics	`read:biometrics`
	`write:biometrics`
Classes & Bookings	`read:classes_and_bookings`
	`write:classes_and_bookings`
	`delete:classes_and_bookings`
Challenges	`read:challenges`
Facilities	`read:facilities`
Reports	`read:reports`
Groups	`read:groups`
	`write:groups`
	`delete:groups`

📘
Quick Tip:
Only request the scopes your app actually needs.
This keeps access tightly scoped, improves security, and follows the principle of least privilege.

⏳ Token Expiration

Client Credentials Tokens

Access tokens issued through the Client Credentials grant expire after 1 hour (3600 seconds).

Authorization Code Flow Tokens

Access tokens issued through the Authorization Code Flow with PKCE have the following lifespans:

Access Token: Expires after 1 hour (3600 seconds)
Refresh Token: Expires after 30 days (when provided)

🔄 Best Practice

Your application should treat access tokens as short-lived and be prepared to:

Store tokens temporarily in memory or secure storage
Automatically request a new token when the current one expires
Use refresh tokens (when available) to obtain new access tokens without re-authentication
Avoid hardcoding tokens—they're tied to time and credentials

For Client Credentials: Request a new token before each batch of API calls or implement a caching strategy with automatic refresh.

For Authorization Code Flow: Use the refresh token to obtain new access tokens when they expire.

💡
Quick Tip
Token responses include an expires_in field (in seconds), which your app can use to calculate when to refresh:
{ 
  "access_token": "...", 
  "expires_in": 3600, 
  "token_type": "Bearer",
  "refresh_token": "..." // Only for Authorization Code Flow
}

🧪 See It in Action

Want to see how to authenticate and get an access token using OAuth 2.0?

👇 Check out our recipe to learn how to use client credentials:

Request an access token from our auth portal
Authenticate securely using your client ID and secret (Client Credentials)
Use tokens to make authorized API requests

👇 Check out our recipe to learn how to use authorization code flow:

Request an access token from our auth portal
Authenticate securely using your client ID and secret

👇 Check out our recipe to learn how to use OIDC:

Request an access token from our auth portal
Authenticate securely using your client ID (OIDC)