# Management API

> The API the CMS itself uses, for scripts and integrations that change content.

Source: https://docs.bifrostorbit.com/cms/developers/management-api/

Everything the CMS screens do goes through the management API. From scripts and integrations, call it at `https://api.bifrostorbit.com/cms/manage/v1` (staging: `https://api-stage.bifrostorbit.com/cms/manage/v1`). It follows the scope of the screens:

```
/cms/manage/v1/organisations/{organisationId}/spaces/{spaceId}/environments/{environmentId}/regions/{regionId}/locales/{localeId}/content/{contentId}
```

## Signing in

- **In the browser:** the Orbit session cookie.
- **From scripts:** a management token (`cms_mt_…`) created on the organisation's **Management tokens** page, as `Authorization: Bearer <token>`. It acts as the person who created it, within their permissions.

## Answers

JSON with `data` on success and `{ "error": { "code", "message", "details" } }` on failure. Send the `docVersion` you read with every update. If the page has changed since, the save is refused with `409` and the message names both versions; `details.currentVersion` holds the version to read again before you retry. Invalid values come back as `400` with every problem in `details`, as `{ "path", "message" }`.

## Fields and links

Fields are checked as described in [Field types](https://docs.bifrostorbit.com/cms/developers/field-types/). Two rules matter most for scripts:

- **Conditional fields.** A field with `showWhen` in the schema is only required and checked while its condition holds. Leave it out otherwise; any value it holds is kept but not delivered.
- **Links to pages.** Send `{ "kind": "content", "contentId": "<page id>" }` to link to a page, so the link follows the page when it moves. The page must be in the same space and not in the bin. Send `{ "kind": "url", "href": "https://…" }` for any other address.

## Shared sections

A shared section is an entry of the `sharedSection` content type whose body holds its blocks. A page places it with a `sharedSection` block whose `section` field holds the section's id. When you save a page, blocks you send in that block's `blocks` slot are saved to the section, not the page, so every page showing it changes; the page keeps only the block that points at the section. Reading a page gives the pointer with an empty slot. Deleting a section that pages still use is refused with `400`, naming the pages.

## Permissions

Every route checks the same permissions as the screens. See [Roles and permissions](https://docs.bifrostorbit.com/cms/editors/roles-and-permissions/).