---
title: "The token scope catalogue"
method: GET
path: "/scopes"
tags: ["admin"]
---

# The token scope catalogue

`GET /scopes`

## Request

- Base URL: `https://api.letsship.ai/v1`
- URL: `https://api.letsship.ai/v1/scopes`
- Auth: none declared

The scope vocabulary grouped for a consent decision: one row per resource, each with ordered access levels naming the exact scopes they grant. Served so the console, the CLI and MCP read the same rows as the enforcement vocabulary, rather than each keeping a copy that can drift from it. Static content — it describes what CAN be granted, not what the caller may grant; pair it with the `grantableScopes` on the caller's session for that.

## Response `200`

The catalogue.

- ScopeCatalog
  - `groups` ScopeGroup[], required
    - `id` string, required
    - `title` string, required
    - `description` string, required
    - `levels` ScopeAccessLevel[], required: Ordered least to most privileged, and cumulative — each level is a superset of the one before it.
      - `id` string, required
      - `label` string, required
      - `scopes` string[], required: Exactly what this level grants. Empty means no access.
      - `reserved` boolean: True when this level grants a scope that currently gates no route. Per-level, not per-group: a caller whose ceiling hides the reserved level must not see the group's note attached to an ordinary one.
    - `reservedNote` string: Present when this row's top level grants a scope that currently gates no route.

---

[API](https://skmtc.dev/letsship/apis/ship-api.md) · [All operations](https://skmtc.dev/letsship/apis/ship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/letsship/apis/ship-api/revisions/e6eac1bcadd4?raw)