Scopes

A scope is a permission your application asks the user to grant. Nanako has four, and every one of them affects exactly one thing: which claims /oauth/userinfo returns.

The scopes

Scope	Grants	Claims added to /oauth/userinfo
openid	Nothing on its own	—
profile	Display name and avatar	name, picture
email	Email address	email, email_verified
phone	Phone number	phone_number, phone_number_verified

sub is always returned, for any token, regardless of scope. Every other claim requires its scope.

Claims are omitted, not null, when the underlying value is unset. A user with no phone number returns no phone_number key at all, even when the token carries phone. Read defensively.

About openid

openid unlocks no data. Nanako accepts it because OIDC client libraries send it by default, and it appears in the request-scope default, but nothing branches on it.

You do not need it. If your application was registered through the web form it almost certainly is not permitted to use it — see Always send an explicit scope.

Asking for scopes

Scopes are space-separated in the scope parameter:

&scope=profile%20email

Ask for the minimum. Every scope you add is a line on the consent screen and a reason for the user to hesitate.

Formatting is strict. The value is split on single spaces and each piece must be a recognized scope, so a double space, a leading space or a trailing space produces an empty piece and fails the request:

{"error": "invalid_scope", "error_description": "scope '' 不被允许"}

How scope is validated

Your application has a permitted set, fixed at registration and editable from the Developer page. The authorization request is checked against it: if any requested scope is outside the set, the request is rejected with invalid_scope before the user sees anything.

requested scope ── ⊆ permitted set? ──► consent screen ──► granted scope
                         │
                         └── no ──► 400 invalid_scope

The granted scope is what comes back in the token response and what the access token carries. Read it from the response rather than assuming you were given what you asked for.

Re-authorizing with a different scope

Nanako remembers the scope string a user approved. If you later send a request with a different scope string, the user is shown the consent screen again and your grant is updated to the new set.

Matching is on the exact string. profile email and email profile are different, and so are profile and profile — a difference in ordering or spacing causes a needless second consent prompt. Build the scope string once, as a constant, and reuse it.

What a token can reach

An OAuth access token authenticates exactly two calls:

GET /oauth/userinfo	With Authorization: Bearer <access_token>
POST /oauth/revoke	With the token as a form field, plus your client credentials

It does not authenticate the rest of the Nanako API. /api/v1/* endpoints accept only a Nanako session token belonging to the signed-in user, and there is no scope that changes this.

So the honest summary: OAuth 2.0 at Nanako is an identity mechanism. It tells you who the user is. It does not currently delegate access to anything they own.

Checking whether a token is still valid

There is no introspection endpoint. Call /oauth/userinfo: any non-expired, non-revoked token returns 200 with at least sub, and anything else returns 401 invalid_token. That works regardless of which scopes the token carries.