---
name: bolt-disable-api
description: >-
  Use this skill when the user wants to disable, turn off, or lock down Bolt CMS API endpoints, GraphQL, OpenAPI documentation (Swagger UI, ReDoc, Scalar), GraphiQL, or prevent data exposure via the API in development and/or production environments.
title: bolt-disable-api
canonical_url: https://skilld.dev/gh/vondry/bolt-skills/bolt-disable-api
last_updated: 2026-10-23T08:04:15.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [scripts/verify.sh](https://skilld.dev/api/skills-raw/vondry/bolt-skills/bolt-disable-api/scripts/verify.sh).
>
> If the user asked to install this Skill, run `npx skilld install vondry/bolt-skills/bolt-disable-api`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/bolt-disable-api`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/vondry/bolt-skills/bolt-disable-api) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/bolt-disable-api`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/bolt-disable-api --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/bolt-disable-api --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Disabling API, GraphQL, and OpenAPI Docs in Bolt CMS

This skill guides an agent on how to completely turn off the REST API, GraphQL, and OpenAPI documentation in Bolt CMS across Development and Production environments, or lock down permissions to eliminate unauthorized data exposure.

## Core Architecture Context

Bolt CMS bundles API Platform (`api-platform/core` v4) and Webonyx GraphQL (`webonyx/graphql-php`). By default:
- OpenAPI / Swagger UI is served at `/api/docs.html` and raw schema at `/api/docs.jsonopenapi`.
- GraphiQL IDE is served at `/api/graphql/graphiql`.
- The GraphQL endpoint is active at `/api/graphql`.
- Core entities (`Content`, `Field`, `Relation`) grant read permissions (`api:get`) to `PUBLIC_ACCESS`.
- **The backend depends on the API Platform routes.** The admin listings (dashboard, content overviews) normalise records with the `json_records` Twig filter, which runs API Platform's normalizer, and that normalizer generates an IRI (`/api/contents/{id}`) for every record from the `_api_*` routes. Without those routes every listing fails with `Unable to generate an IRI for the item of type "Bolt\Entity\Content"`.

So the API is shut down by **blocking requests, never by removing routes**: the routes stay registered for IRI generation, the firewall (Step 4) denies every request to `/api`, the documentation engines and GraphiQL are off (Step 2) and the permissions are revoked (Step 3); Step 5 also limits CORS to the API.

---

## Step-by-Step Procedure

### 1. Keep the API Platform Routes Registered
File: `config/routes/api_platform.yaml`

Leave the `api_platform` resource loader **active** and keep `api_entrypoint` (Bolt's backend menu references that route name; removing it causes `RouteNotFoundException`). Do not comment out the loader: the admin needs the `_api_*` routes to generate IRIs (see Core Architecture Context), and the routes expose nothing once Step 4 blocks `/api`. Add a comment so nobody "cleans it up" later:

```yaml
# config/routes/api_platform.yaml

# Must stay registered: Bolt's admin listings generate IRIs from these routes
# ("Unable to generate an IRI" otherwise). The public API is blocked by the
# '^/api(/|$)' ROLE_NO_ACCESS rule in security.yaml (bolt-disable-api).
api_platform:
  resource: .
  type: api_platform
  prefix: /api

api_entrypoint:
  path: '%bolt.backend_url%/api'
  controller: api_platform.action.documentation
```

If an earlier run of this skill commented out the loader, restore it and run `bin/console cache:clear`.

---

### 2. Disable Documentation Engines & GraphiQL Master Flags
File: `config/packages/api_platform.yaml`

Add the documentation and GraphiQL disable flags under the root `api_platform:` key to apply across both development and production environments:

```yaml
# config/packages/api_platform.yaml

api_platform:
  enable_entrypoint: false
  enable_docs: false
  enable_swagger: false
  enable_swagger_ui: false
  enable_re_doc: false
  enable_scalar: false
  graphql:
    graphiql:
      enabled: false
    introspection: false
  mapping:
    # Keep Bolt core's entities: removing this path drops Bolt's API resources and differs
    # from every stock Bolt project. Disabling happens through flags, permissions and the firewall.
    paths: [ '%kernel.project_dir%/vendor/bolt/core/src/Entity', '%kernel.project_dir%/src/Entity' ]
  formats:
    json: [ 'application/json' ]
    jsonld: [ 'application/ld+json' ]
    jsonapi: [ 'application/vnd.api+json' ]
  serializer:
    hydra_prefix: true
  defaults:
    normalization_context:
      skip_null_values: false
    pagination:
      client_items_per_page: true
      items_per_page_parameter_name: 'pageSize'

when@prod:
  api_platform:
    graphql:
      introspection: false
```

The `when@prod` block repeats the root setting on purpose: it is Bolt's stock block, and keeping it unchanged makes the diff against `bolt/project` smaller.

*(Note: Do not set `api_platform.graphql.enabled: false` because in API Platform 4.3, entity attributes declaring `graphQlOperations` without explicit class options trigger a TypeError during Doctrine parameter compilation. The firewall rule in Step 4 achieves full disabling cleanly without this bug).*

---

### 3. Revoke API Permissions & Hide Admin Maintenance Menu Link
File: `config/bolt/permissions.yaml`

1. Change `api_admin: [ ROLE_ADMIN ]` to `api_admin: []` (or `!*`) so the "Bolt API" item is hidden from the Bolt Admin Maintenance menu.
2. Change `api:get: [ PUBLIC_ACCESS ]` to `[ ROLE_ADMIN ]` (or `[]`) to block unauthorized data reading.

```yaml
# config/bolt/permissions.yaml

  # Hide "Bolt API" link from admin menu
  api_admin: []

  # Revoke public data reading
  api:get: [ ROLE_ADMIN ]
  api:post: [ ROLE_ADMIN ]
  api:delete: [ ROLE_ADMIN ]
```

---

### 4. Firewall Lockdown (the Block)
File: `config/packages/security.yaml`

This rule is what turns the API off. Add it as the **first** entry of `security.access_control` so it rejects every request to the `/api` path segment. Nothing grants `ROLE_NO_ACCESS` (keep it out of `role_hierarchy`), so logged-in admins are refused too: anonymous requests get `401`, authenticated ones `403`.

```yaml
# config/packages/security.yaml

security:
  access_control:
    # Public REST/GraphQL API disabled (bolt-disable-api). (/|$) limits the rule to /api and /api/… —
    # a bare '^/api' would also block pages such as /apiary.
    - { path: '^/api(/|$)', roles: ROLE_NO_ACCESS }
```

The backend does not call `/api/*` from the browser (it uses `/bolt/*` and `/bolt/async/*`), so this rule never affects the admin.

---

### 5. Limit CORS to the API
File: `config/packages/nelmio_cors.yaml`

Bolt's stock configuration applies the CORS defaults to every path (`'^/': ~`). Nothing but the API needs cross-origin access, so limit it — with the API blocked, the rule only ever applies to denied responses:

```yaml
# config/packages/nelmio_cors.yaml
nelmio_cors:
  defaults:
    origin_regex: true
    allow_origin: [ '%env(CORS_ALLOW_ORIGIN)%' ]
    allow_methods: [ 'GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE' ]
    allow_headers: [ 'Content-Type', 'Authorization' ]
    expose_headers: [ 'Link' ]
    max_age: 3600
  paths:
    '^/api/': ~
```

Keep `CORS_ALLOW_ORIGIN` at its localhost default unless a real consumer on another origin exists (the lock-down variant); never `*`.

---

### 6. Validate YAML & Clear Caches

Always validate YAML configs and clear Symfony caches:

```bash
bin/console lint:yaml config --parse-tags
bin/console cache:clear
APP_ENV=prod bin/console cache:clear
```

---

## Verification & Testing

Verify that the lockdown succeeded using the following checks:

### 1. Check Routing
Run:
```bash
bin/console debug:router | grep -c " _api_"
```
Expect a non-zero count: the API Platform routes must stay registered (Step 1). `0` means the loader was commented out and the admin listings will fail with "Unable to generate an IRI".

### 2. Check the Firewall Rule
Run:
```bash
bin/console debug:config security access_control
```
The first entry must be `path: ^/api(/|$)` with `roles: [ROLE_NO_ACCESS]`, and no other rule matching `/api` may come before it.

### 3. Run Verification Script
Execute the bundled test script (set `BOLT_BASE_URL` to this project's running site for the HTTP checks; default `http://127.0.0.1:8000`):
```bash
BOLT_BASE_URL=http://localhost:8080 vendor/tomvondracek/bolt-skills/skills/bolt-disable-api/scripts/verify.sh
```
Or verify manually via `curl` (every endpoint must be refused; `404` is acceptable only where the feature is switched off — the documentation and GraphiQL. A `404` on a data endpoint means the routes are gone, which breaks the admin):
- `curl -i http://127.0.0.1:8000/api` -> Expect `404` (the entrypoint is off; routing answers before the firewall)
- `curl -i http://127.0.0.1:8000/api/contents` -> Expect `401` or `403`
- `curl -i http://127.0.0.1:8000/api/contents/1` -> Expect `401` or `403`
- `curl -i http://127.0.0.1:8000/api/docs.html` -> Expect `401`, `403` or `404`
- `curl -i http://127.0.0.1:8000/api/docs.jsonopenapi` -> Expect `401`, `403` or `404`
- `curl -i http://127.0.0.1:8000/api/graphql/graphiql` -> Expect `401`, `403` or `404`
- `curl -i -X POST http://127.0.0.1:8000/api/graphql -H "Content-Type: application/json" -d '{"query":"{ contents { edges { node { id } } } }"}'` -> Expect `401` or `403`
- `curl -i http://127.0.0.1:8000/index.php/api/contents` -> Expect `401` or `403` (front-controller path), or on Apache with `bolt-htaccess` a `301` to `/api/contents`. A `200` HTML page is not the API but a front-controller path that is not redirected — fix it with `bolt-htaccess` Pitfall 10. `verify.sh` sends this request only when `public/.htaccess` has the Pitfall 10 rules; without them the request would put `/index.php` into Bolt's cached links. The API firewall matches the same path info as the router, so the path cannot bypass it.

### 4. Check the Backend
Log in to `/bolt/` and open the dashboard and at least one content listing (`/bolt/content/<contenttype>`). Both must render. A 500 with "Unable to generate an IRI" means the API Platform routes were removed (Step 1). Clear the cache first (`bin/console cache:clear`): Bolt caches normalised records, so a warm cache can hide the error until the next deploy.

## Pitfalls

- **Commenting out the `api_platform` route loader breaks the admin.** It looks like the cleanest way to remove the API, and older versions of this skill recommended it, but the admin generates IRIs from those routes. Block `/api` in the firewall instead.
- **A warm cache hides the breakage.** The error appears only after `cache:clear` or a deploy, often days later and after unrelated commits. Always clear the cache and open the admin listings after changing API configuration.
- **The firewall rule is the only thing blocking requests.** Removing or narrowing `^/api(/|$)` reopens the API (protected only by the `api:*` permissions). `verify.sh` checks the rule and the live endpoints; keep it in the audit.
