> For the complete documentation index, see [llms.txt](https://guide.fariaedu.com/integrations-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.fariaedu.com/integrations-portal/schoolsbuddy/recipes/authenticating-by-region-identity-and-public-api-servers.md).

# 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.

{% hint style="info" %}
Before following this guide, generate a Client ID and Client Secret — see [Creating an Auth Client](/integrations-portal/schoolsbuddy/recipes/schoolsbuddy-api-authentication-creating-an-auth-client.md).
{% endhint %}

## 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`       |

{% hint style="warning" %}
**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.
{% endhint %}

## 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](/integrations-portal/schoolsbuddy/recipes/schoolsbuddy-api-authentication-creating-an-auth-client.md). 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.

{% hint style="success" %}
**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.
{% endhint %}