Connecting Umbraco
Cora can read your Umbraco website and save drafts of pages, in the missions you choose. Every draft waits for an approval card, always. Cora never publishes, unpublishes, deletes, moves or sorts anything. A person publishes in Umbraco when the draft is right.
You connect the site once for the whole organisation, with one Umbraco API user. Two people take part:
- Your Umbraco admin makes a user group and an API user for Cora, and copies its client id and secret (step 1).
- A Cora org admin enters them on the Connections page (step 2).
Then any mission member can switch the connection on in their mission (step 3). This page uses an invented company, Kestrel Cycles, whose website is https://www.kestrelcycles.example.
What you need
Section titled “What you need”- Umbraco 15 or newer. Older versions have no API users, so they cannot connect.
- A website address that anyone on the internet can reach over https.
- An Umbraco admin who can manage users and user groups in the backoffice.
- An org admin in Cora, with MCP turned on for the organisation (see Connecting an MCP server).
Step 1: your Umbraco admin makes an API user
Section titled “Step 1: your Umbraco admin makes an API user”Make a user group for Cora
Section titled “Make a user group for Cora”The group decides what Cora can see and change on the Umbraco side. It is a second guard, behind Cora’s own limits.
- In Umbraco’s backoffice, open Users, then User groups, and create a group, for example Cora drafts.
- Give it access only to the content and media Cora should work on: set its start nodes to those parts of the site.
- Turn off the Publish, Unpublish and Delete rights. Leave Browse, Create and Update on.
- Save.
Make the API user
Section titled “Make the API user”- In Users, choose Create, then API User.
- Give it a name, such as Cora AI, and an email address.
- Add it to the Cora drafts group, and to no other group.
- Save.
Add client credentials
Section titled “Add client credentials”- On the API user, find Client credentials and choose Add.
- Enter a client id. It must start with
umbraco-back-office-, for exampleumbraco-back-office-cora. - Umbraco shows the client secret once. Copy the client id and the secret.
Give them to the Cora org admin in a safe way, such as a password manager. Do not email or chat them.
Step 2: a Cora org admin connects the site
Section titled “Step 2: a Cora org admin connects the site”- In Cora, open Connections on the left rail. Under Needs an admin to set up first, find Umbraco CMS (it says Organisation setup needed) and press Set up beside it. On its page, the Account section has the Umbraco CMS card: choose Set up.
- Fill in:
- Site address: https and just the site, with no path, for example
https://www.kestrelcycles.example; - Client id: the one from step 1, starting with
umbraco-back-office-; - Client secret;
- Who approves drafts: the admin role whose people get the approval cards.
- Site address: https and just the site, with no path, for example
- Choose Test connection. Cora signs in and says how many top-level pages it can see, for example “Connected. Cora can see 12 top-level pages.”
- Choose Save.
The secret is kept in a secrets store and is never shown again. The card says only Secret set and the date. Cora’s worker and the hosted server never see it.
Later you can:
- Test connection: check that the stored sign-in still works.
- Change: a new site address, client id or approval role. A new address or client id needs the secret typed again, so a stored secret is never sent to a different site.
- Replace secret: when your Umbraco admin makes a new secret.
- Remove: Cora deletes the secret and stops using the site in every mission at once.
If the card says Umbraco is not ready yet, the Cora AI operator has not finished setting it up. Ask them.
Step 3: switch it on in a mission
Section titled “Step 3: switch it on in a mission”- Open the mission and its details (the Details button at the top right), then the Tools tab, under Connections.
- In the Connections section, find Umbraco CMS and switch it on.
Any mission member can switch it on or off. Cora can then use the site in that mission, and in no other.
Then ask Cora in the mission’s dialogue, for example: “List the pages under About us” or “Draft a new page under News about our spring opening hours.”
What Cora can read and save
Section titled “What Cora can read and save”Cora works as the one API user, so she sees only what its group allows.
She can read:
- pages: the top level, the pages under a page, a page by id, a search, a page’s addresses and whether it is published;
- document types and data types;
- media items and folders;
- the audit log of one page or one media item (Umbraco 15 has no audit log for the whole site).
She can save drafts:
- create a page as a draft;
- change a draft’s properties;
- change a draft’s name.
Every draft waits for an approval card, always. No setting, mission switch or read-only mark can turn this off. When the card is approved, Cora saves the draft in Umbraco. The page’s published version does not change until someone publishes it in Umbraco.
Cora never publishes, unpublishes, deletes, moves, sorts or copies anything, and never touches the recycle bin, public access, templates, users or settings. Those tools are not on her list, even if Umbraco offers them.
If it does not work
Section titled “If it does not work”- The site refused the sign-in: the client id or secret is wrong, or the API user was removed. Ask your Umbraco admin for a new secret and choose Replace secret.
- The site has no Umbraco sign-in at that address: check the site address. Umbraco 14 and older cannot connect.
- The site did not answer: the site is down or blocks Cora. Try again later, or ask your web host.
- The address is refused: type just the site over https, such as
https://www.kestrelcycles.example, with no path, port or user name. - Cora asks for the secret when you change the site address or the client id: type it again. Cora never sends a stored secret to a new site.
- A draft is refused in Umbraco: the API user’s group may not have access to that part of the site. Ask your Umbraco admin to check its start nodes.
What stays private
Section titled “What stays private”- The client secret is kept in the secrets store. It never appears in the database, logs, audit entries, prompts or on any page.
- Cora’s API swaps the client id and secret for a short-lived token. The worker holds that token for one step only.
- One organisation’s site is used only for that organisation.