Choosing Scopes – Developer Guide | Help Center

Scopes define the range of things an app can do in Manabu2. You choose them as checkboxes on the app registration screen. This article explains what each scope means and why some can only be granted by organization admins.

The key idea: a scope is a ceiling

Get this wrong and you'll get your settings wrong.

What an app can actually do is limited to the overlap of all three of the following:

The scopes allowed for the app (what you set on this screen)
The scopes the app requested at sign-in
The permissions of the user who signed in

So even if you allow an app read:reports, a regular employee who has no permission to view reports still can't get reports through that app. Allowing a scope does not give users any permissions.

Put the other way round, allowing broader scopes than you need doesn't mean "anyone can do anything." There's still a good reason to keep them narrow, which the next sections explain.

List of scopes

Learner scopes (developers can allow these)

Scope	Meaning	Typical use
`read:catalog`	View courses (コースを見る)	Listing courses, learning paths and certificates
`read:content`	Read lesson content (レッスン内容を読む)	Fetching lesson text, materials and quiz questions
`read:progress`	View own progress (自分の進捗を見る)	Showing the user's own progress, assignments and certificates
`write:progress`	Record progress (進捗を記録する)	Recording lesson views and completions, submitting quizzes

A mobile app for learners usually needs only these four.

Admin scopes (only organization admins can allow these)

Scope	Meaning	Typical use
`read:members`	View members (メンバーを見る)	Getting the organization's member list
`write:members`	Change members (メンバーを変更する)	Syncing employee data with your HR system
`read:reports`	View reports (レポートを見る)	Feeding learning data into a BI tool
`webhooks:manage`	Manage webhooks (Webhook を管理する)	Registering and removing event notifications
`write:content`	Edit learning content (教材を編集する)	Creating and editing courses, sections, lessons and tests
`apps:manage`	Manage apps (アプリを管理する)	Registering, changing and deactivating this organization's apps

Why admin scopes are kept separate

If a scope is only a ceiling and never grants permissions, it might seem fine to let developers pick whatever they like. But there is one loophole.

An app can become a vessel for someone else's permissions.

Suppose a developer registers an app that requests write:members, and then an organization admin or HR staff member signs in to it. The token they get carries write:members. That token is then delivered to the redirect URI the developer chose, into code the developer wrote.

Developers can't give themselves permissions. But they could build an app that acts with someone else's permissions the moment a person who holds them uses it.

That's why granting admin scopes is limited to organization admins. Admins already hold those permissions themselves, so nothing new can be gained this way.

If you're building an app that needs admin scopes, ask an organization admin to register it (or to add the scopes). With just the developer role you can still edit the app's other settings, and saving your edits won't quietly remove admin scopes that have already been granted.

Choosing scopes in practice

Mobile app for learners

read:catalog
read:content
read:progress
write:progress

Embedded display in an internal portal

read:catalog
read:progress

If you only display data, you don't need write access.

HR system integration (registered by an admin)

read:members
write:members

An API key may be a better fit for this.

When in doubt, choose the narrower option. You can always add more scopes later. Overly broad scopes widen the damage if the app has a bug or is compromised.

API keys work differently

An API key holds its scopes outright, with no user involved. Unlike an app token, it isn't narrowed down to what a particular user is allowed to do.

So choosing scopes for an API key is choosing its permissions directly, even more so than for an app. Here too, only organization admins can grant admin scopes.

Choosing Scopes – Developer Guide