S
Scholé
Integration API
Getting Started

Connect to the API

Everything you need to make your first authenticated request: base URL, authentication schemes, request conventions, pagination, and error handling.

Base URL

All API endpoints are relative to the versioned base URL.

text
https://app.schole.ai/api/v1/
Content type
All requests must send Content-Type: application/json and all responses are JSON. File uploads use multipart/form-data.
Authentication

The API supports two authentication schemes. Both produce a standard Authorization: Bearer <token> header.

JWT Bearer
User-facing integrations

Short-lived access token obtained by posting credentials. Good for user-delegated access and internal tooling.

simplejwt
OAuth2 Client Credentials
Recommended for M2M

Server-to-server token flow. No human credentials stored in your pipeline. Scoped to a registered application.

RFC 6749 §4.4

JWT Bearer Tokens

Post credentials to obtain an access / refresh token pair. Access tokens expire after 5 minutes; refresh tokens after 24 hours.

1
Request a token pair
bash
curl -X POST https://app.schole.ai/auth/jwt/create/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "service-account@yourcompany.com",
    "password": "••••••"
  }'
json — response
{
  "access":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
2
Use the token on every request
bash
curl https://app.schole.ai/api/v1/users/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
3
Refresh when the access token expires
bash
curl -X POST https://app.schole.ai/auth/jwt/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'

OAuth2 Client Credentials

The recommended flow for machine-to-machine integrations. Your application gets its own client_id and client_secret; no user password leaves your system.

1
Register an OAuth2 Application

Ask your Scholé administrator to create an Application in the admin panel (/admin/oauth2_provider/application/add/) with:

FieldValue
Client typeConfidential
Authorization grant typeClient credentials
Namee.g. Swisscom MIS Integration

You will receive a client_id and client_secret.

2
Exchange credentials for a token
bash
curl -X POST https://app.schole.ai/oauth/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
json — response
{
  "access_token": "xxxxxxxxxxxxxxxxxxx",
  "token_type":   "Bearer",
  "expires_in":   36000,
  "scope":        "read write"
}
3
Use the token on every request
bash
curl https://app.schole.ai/api/v1/hr/employees/ \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxx"

Tokens expire after expires_in seconds. Simply repeat step 2 to obtain a fresh token — the client credentials flow has no refresh token.

Error Handling

Errors return a JSON body with a detail field (and sometimes a structured errors map for validation failures).

json — validation error (422)
{
  "detail": "Validation error",
  "errors": {
    "email":    ["Enter a valid email address."],
    "team_id":  ["Object with id=99 does not exist."]
  }
}
StatusMeaning
200 OK / 201 Created Request succeeded
204 No Content Delete or deactivate succeeded (empty body)
400 Bad Request Malformed JSON or missing required fields
401 Unauthorized Missing or invalid Authorization header
403 Forbidden Token is valid but lacks permission for this resource
404 Not Found Resource doesn't exist or belongs to another company
422 Unprocessable Entity Field-level validation failure — check the errors map
429 Too Many Requests Rate limit exceeded — Retry-After header present
500 Internal Server Error Unexpected server error — contact support
Next Steps
Swagger UI
Try all 44 endpoints interactively in the browser
Generate an SDK
Auto-build a typed client for Python, Java, .NET, or JS