Connected App API Reference

Campus One exposes a RESTful gateway for registered third-party applications. Using this gateway, connected apps can interact programmatically with Nile's digital campus—pushing real-time notifications and weekly calendar events directly to students who have consented.

To help developers build and debug integrations rapidly, our entire App API is self-documenting and strictly compliant with the OpenAPI 3.0 specification.

Live OpenAPI Documentation

Campus One hosts an interactive Reference UI and a raw JSON specification directly on the API server. These endpoints are completely public so that integration developers can explore schemas, return codes, and test payloads without requiring an access token:

• Interactive Reference UI: https://auth.campusone.com.ng/api/apps/docs
• Raw OpenAPI Spec JSON: https://auth.campusone.com.ng/api/apps/spec.json

[!TIP] You can import the raw spec.json directly into Postman, Insomnia, or code generation toolchains (e.g., OpenAPI Generator, Orval, or Swagger Codegen) to quickly scaffold client SDKs for your applications.

Global Authentication

All secure routes under /api/apps/* require token-based authentication using the student's OIDC access token.

• Header Name: Authorization
• Format: Bearer <access_token>

The access token must be obtained through the SSO Authorization flow. The token securely encodes the authorizing student's ID and your registered client application ID, meaning you never need to supply sensitive identifiers (like a userId) inside request payloads.

POST /api/apps/notifications HTTP/1.1
Host: auth.campusone.com.ng
Authorization: Bearer c1_act_abc123xyz
Content-Type: application/json

Safe Retries with Idempotency

Network failures or server timeouts can occasionally leave your application unsure if a write request succeeded. Re-sending the request blindly could cause unwanted side-effects (e.g., sending duplicate notifications or calendar events).

To prevent duplicates, all write endpoints support safe retries via Idempotency Keys:

• Header Name: Idempotency-Key
• Value: A unique string of your choice (e.g., a UUID or a composite string like booking-event-12345).
• Scope: Scoped uniquely per-app and per-endpoint.

How it Works

When the API gateway receives a request with an Idempotency-Key header:

1. Cache Lookup: The gateway checks our Cloudflare KV cache for an existing result associated with your client ID and that specific key.
2. Cache Hit: If a matching key is found, the server immediately returns the originally saved result and status code directly from the cache—without executing any database writes or downstream actions.
3. Cache Miss: If no matching key is found, the server processes the request, commits the database write, and saves the successful response payload in the cache (expires after 24 hours) before returning the response.

[!WARNING] Idempotency keys must be unique. Sending different request payloads with the same Idempotency-Key will return the cached response of the first request, not the updated data.

Status Codes & Errors

Successful write requests return 200 OK with the full created record as the JSON body.

There are two error body shapes depending on where the request is rejected:

Authentication failures (401) are rejected at the gateway and return a simple object:

{ "error": "Invalid access token" }

Validation and authorization failures (400 / 403) come from the endpoint and return the richer error object (code, status, message, and — for validation — a data.issues array):

{
  "defined": false,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "Token lacks 'notifications' scope"
}

The interactive reference UI and spec.json are the authoritative, always-current source for every schema and status code.

Core API Endpoints

Explore detailed references for the core functional REST endpoints:

• Programmatic Notifications API: Send real-time push alerts to user shells.
• App Events API: Push calendar schedules and timetable bookings to student dashboards.