Permissions & Scopes

When you connect an app to Campus One, an admin selects which data scopes your app is allowed to request. Students are shown a consent screen listing the granted scopes when they first sign in.

[!NOTE] Scopes are delivered today via OpenID Connect — the only live SSO protocol. The SAML attribute mapping at the bottom of this page describes a planned SAML integration that is not yet available.

Scope reference

openid (always required)

Always present. Returns the user's stable unique identifier (sub). This is a random opaque string — it is not the student ID.

{ "sub": "clx8z2abc123" }

profile

Returns profile attributes. The standard name claim is always included; the profile scope adds the user's preferred display name and phone number (when set).

{
  "name": "Salih Ibrahim",
  "preferred_username": "Salih I.",
  "phone_number": "+234..."
}

Default: enabled for new apps (controlled by the app's permProfile flag).

email

Returns the student's university email address.

{
  "email": "256240001@nileuniversity.edu.ng",
  "email_verified": true
}

Default: enabled for new apps (part of permIdentity).

academic

Returns academic record data. Useful for apps that need to know a student's department, faculty or level, and where they sit in the academic calendar.

{
  "student_id": "256240001",
  "study_level": "undergraduate",
  "level": 300,
  "final_year": false,
  "faculty_id": "fac_eng",
  "department_id": "dept_cs",
  "academic_session": "2025/2026",
  "semester": "harmattan"
}

faculty_id and department_id are stable Campus One identifiers, not display names. Resolve them through your own lookup if you need human-readable labels.

academic_session and semester ("harmattan" | "rain") describe the current term, and final_year is true once the student's level reaches their department's maximum. Note that level auto-advances each Harmattan semester — see Session, semester & level progression for the full contract.

Default: enabled for new apps (controlled by permAcademic).

calendar

Read-only access to the student's timetable.

Default: disabled — must be explicitly enabled by an admin (permCalendar).

notifications

Allows your app to send notifications to the student through Campus One's notification pipeline. See the Notifications API.

Default: enabled for new apps (permNotifications).

events

Allows your app to push calendar events into the student's Campus One dashboard. See the Events API.

Default: disabled — must be explicitly enabled by an admin (permEvents).

roles

Returns the user's full role set. Adds a roles array (every role assigned to the user) and a custom_roles array (your app-specific roles). The top-level role claim — the user's primary role — is always present regardless of this scope. See External Access & Roles.

Default: disabled — must be requested.

offline_access

Returns a refresh token so your app can mint new access tokens without redirecting the user again. See token lifecycle.

Default: disabled — must be requested.

Scopes ↔ app permission flags

Each scope is gated by a permission flag on your app's SSO config. A scope is only fulfilled when both the admin has enabled the flag and your app requests the scope. Toggle these in the developer dashboard under your app → Permissions.

SAML attribute mapping

[!WARNING] Planned — not yet available. SAML 2.0 is not implemented yet; Campus One issues identity exclusively over OIDC today. The mapping below documents the intended future SAML assertion attributes.

For future SAML integrations, the same data will be delivered as assertion attributes:

Requesting scopes at runtime

Specify scopes in your authorization request. Only scopes that an admin has granted for your app will be fulfilled — requesting an ungranted scope returns error=invalid_scope.

scope=openid profile email academic

Updating permissions

Request scope changes through the developer dashboard: open your app → Permissions tab → toggle the desired scopes → Save. Changes take effect for new sign-in sessions immediately but do not invalidate existing tokens.

Dynamic App Access Grants & Custom Roles

Campus One supports dynamic App Access Grants and Custom Role Assignments per registered application. This allows administrators to assign specific custom roles (e.g. editor, tutor, moderator) directly to users for your application.

When a student or staff member signs in to your connected application:

1. Scope Verification: If your client requests the roles scope during the OIDC flow, their assigned roles are dynamically injected into their OIDC tokens.
2. Access Token Claims:
   • role: The user's primary academic role (e.g., "student" or "staff").
   • roles (Array): Merges their global academic role with your app-specific custom roles (e.g., ["student", "editor"]).
   • custom_roles (Array): Contains only your app-specific roles assigned to this user (e.g., ["editor"]).

Connected applications can parse these claims from the access token and utilize them in route guards or API authorization policies.

The reserved unit_admin role

Every app also shares one fixed, reserved role — unit_admin — which you never have to declare. Assigning it (in the app drawer's Access tab) marks a user as your app's "manager": "unit_admin" is included in their roles / custom_roles claims and it lets them administer your app's access list inside Campus One. Only the app owner or a platform admin can assign it. See the reserved unit_admin role for the full contract.