API Permission Model#

Misskey's API permission model has two layers: endpoint metadata flags that declare what privilege an endpoint requires, and runtime enforcement in ApiCallService that evaluates those flags against the caller's identity and roles. All permission checks run inside ApiCallService.call() before the endpoint handler executes.

Endpoint Metadata (IEndpointMeta)#

Every endpoint exports a meta object typed as IEndpointMeta, defined in packages/backend/src/server/api/endpoints.ts. The fields relevant to permissions are:

TypeScript enforces these constraints via a discriminated union: setting requireCredential, requireModerator, or requireAdmin to true requires kind to be set; setting secure: true is incompatible with those flags 1.

Permission Check Order (Runtime)#

Inside ApiCallService.call(), checks run in this order:

1. secure check — if meta.secure and the request carries a token (rather than a first-party session), throw ACCESS_DENIED 2.
2. Rate limiting — applied before auth checks 3.
3. Credential check — if requireCredential, requireModerator, or requireAdmin, the user must be non-null and non-suspended 4.
4. prohibitMoved check — rejects migrated accounts 5.
5. Role check — if requireModerator or requireAdmin, and the caller is not the root user, RoleService.getUserRoles() is called 6:
   • requireModerator: at least one role must have isModerator or isAdministrator set.
   • requireAdmin: at least one role must have isAdministrator set.
6. requiredRolePolicy check — if set, the caller's policies are evaluated; administrators bypass this check 7.
7. OAuth scope check — if the request uses an access token, its permission array must include meta.kind 8.

The Root User — Special Implicit Privilege#

The root user is the first account created on an instance, stored as meta.rootUserId 9. The root user bypasses all role checks — it is always treated as both administrator and moderator — even without any roles assigned 10. This is enforced in both ApiCallService and directly in RoleService.isAdministrator() / RoleService.isModerator().

The admin/accounts/create endpoint demonstrates the root-user bootstrap case: if rootUserId is null (no accounts yet), the endpoint accepts an unauthenticated request to create the first account. Once rootUserId is set, only the root user — via a first-party session (no external token) — can call the endpoint 11.

Role Definitions#

Administrator and moderator privileges are flags on the MiRole model:

• MiRole.isAdministrator — grants admin-level access.
• MiRole.isModerator — grants moderator-level access.

Administrators are a strict superset of moderators: RoleService.isModerator() returns true if the user has either isModerator or isAdministrator on any of their roles; RoleService.isAdministrator() requires isAdministrator specifically 12. Roles are resolved — including conditional/formula-based roles — via RoleService.getUserRoles().

Custom Inline Permission Logic#

Some endpoints do not rely solely on metadata flags and instead write additional checks inside the handler itself. admin/accounts/create is one example: the endpoint declares no requireAdmin or requireCredential flags and instead performs its own inline logic to cover both the initial-setup path and the subsequent admin-only path 13.

This pattern is appropriate when permission rules depend on runtime server state (e.g., whether setup has been completed) rather than the caller's role.

Key Source Files#