Skip to main content
Version: 1.1

Introduction

Xporter exposes a compliant IMS Global OneRoster v1.1 API that allows third-party systems to retrieve rostering data (organisations, users, classes, enrolments, and academic sessions) from schools connected to the platform.

The Xporter web layer proxies requests to an internal Azure Functions back-end. Each function authenticates the caller by decrypting the Xporter bearer token and then executes a parameterised stored procedure against the identity database.

Base URL​

https://xporter.groupcall.com/api/ims/oneroster/v1p1

Architecture overview​

Integrator
    │
    │  POST /token  (Basic auth: client_id:client_secret)
    ▼
Xporter Web (OneRosterController)
    │  forwards Xporter Bearer token + query string
    ▼
Identity API (Azure Functions — OneRoster.cs)
    │  validates token via IdaasAuthorization.DecriptXodToken
    │  executes stored procedure via EntityFrameworkContext
    ▼
Identity SQL Database (gcidm schema)

Authentication​

This API uses OAuth 2.0 client credentials flow. Obtain a token first and include it in all subsequent requests.

Step 1 — Obtain a bearer token​

Send a POST request to the /token endpoint with your client_id and client_secret in a Basic Authorization header:

Authorization: Basic <base64(client_id:client_secret)>

Example request

POST /api/ims/oneroster/v1p1/token HTTP/1.1
Host: xporter.groupcall.com
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Successful response (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Error response (401 Unauthorized)

{
  "error": "invalid_client",
  "error_description": "Request contains an invalid client ID or secret"
}

Step 2 — Call protected endpoints​

Include the token in the Authorization header of every subsequent request:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Query parameter support​

All collection endpoints support the following query parameters. sort, orderBy, and fields are accepted but are not forwarded to the back-end and have no effect.

ParameterImplementedDescription
limit✅Maximum number of records to return. Omitting it returns all matching records.
offset✅Zero-based index of the first record to return. Use with limit for pagination.
filter✅ PartialSingle key='value' expression. Only status is supported. The enrollments endpoint ignores this filter.
sort❌Accepted but ignored.
orderBy❌Accepted but ignored.
fields❌Accepted but ignored.

Filter syntax

filter=status='active'
filter=status='tobedeleted'

Only a single key='value' expression is supported. Complex AND/OR expressions are not parsed.

Error responses​

Failed data requests return 400 Bad Request with a plain-text body (the raw exception message), not JSON. Handle 400 responses accordingly.

CodeScenario
200 OKRequest succeeded.
400 Bad RequestToken invalid/missing or server-side error. Body is plain text, not JSON.
401 UnauthorizedReturned only by POST /token when client credentials are invalid.
403 ForbiddenBearer token absent on a collection endpoint.

Integration checklist​

  • Obtain your client_id and client_secret from the Xporter platform.
  • Call POST /token and cache the access_token — reuse it until expires_in seconds have elapsed.
  • When 400 or 403 is received on a data endpoint, re-authenticate and retry once.
  • Use limit + offset to page through large result sets. Omitting limit returns all records.
  • Use filter=status='active' to exclude soft-deleted records where required.
  • Do not use sort, orderBy, or fields — these are silently ignored.
  • Expect /courses to always return { "courses": [] } (Microsoft SDS stub only).
  • Link users to classes: join users → enrollments → classes via sourcedId.
  • Parent↔child relationships are carried in User.agents, not in a separate endpoint.

Authentication​

Bearer token obtained from POST /token.

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT