Authenticating by Region: Identity & Public API Servers

How to pick the correct Identity and Public API server for your school's region when authenticating with the SchoolsBuddy API

The SchoolsBuddy Public API is split across two kinds of servers, and both must match your school's region.

Before following this guide, generate a Client ID and Client Secret — see Creating an Auth Client.

Two kinds of servers

• Identity servers issue OAuth 2.0 tokens only. They don't serve data endpoints.

• Public API servers serve the actual data endpoints (Activities, Students, Events, etc.). They don't handle authentication.

Region	Identity server (issues tokens)	Public API server (serves data)
EU	identity-eu.schoolsbuddy.net	publicapi-eu.schoolsbuddy.net
Asia	identity-asia.schoolsbuddy.net	publicapi-asia.schoolsbuddy.net
US	identity-us.schoolsbuddy.net	publicapi-us.schoolsbuddy.net
China	accounts.schoolsbuddy.cn	publicapi.schoolsbuddy.cn

A token is only valid on its own region's Public API server. An EU token is rejected by publicapi-us, and so on — the Identity server and Public API server you call must always be from the same region.

Authentication flow

1. Determine your school's region (see above).

2. Request a token from that region's Identity server:

   POST https://identity-{region}.schoolsbuddy.net/connect/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=client_credentials
   client_id={your_client_id}
   client_secret={your_client_secret}

   For China, use https://accounts.schoolsbuddy.cn/connect/token.

3. Call the same region's Public API server with the returned token:

   GET https://publicapi-{region}.schoolsbuddy.net/{endpoint}
   Authorization: Bearer {access_token}

   For China, use https://publicapi.schoolsbuddy.cn.

Scopes

Scopes aren't requested as a parameter in the token request. They're configured per client in the SchoolsBuddy admin portal, under Settings > API Manager, when the Client ID and Client Secret are created — see Creating an Auth Client. The token you receive is automatically issued with whatever scopes were assigned to that client.

Token lifetime

Tokens currently expire after 1 hour. This is a machine-to-machine (client credentials) flow, so refresh tokens are not used — request a new token with your client ID and secret each time your current token expires or is close to expiring.

In Summary

• Identity servers issue tokens; Public API servers serve data — always pick both from the same region.

• A token from one region is rejected by another region's Public API server.

• Scopes are set when the Client ID/Secret is created in Settings > API Manager, not in the token request.

• Tokens last about 1 hour; request a new one via client credentials rather than using a refresh token.

Getting the right server pairing for your school's region is the key to a working SchoolsBuddy API integration.