Help

Umbraco Integration

Connect BlogSEO to your Umbraco site to automatically publish AI-generated articles directly to your content, with full support for rich text, tables, a cover image, inline images, tags, meta descriptions, custom URL slugs, and drafts. It works with any modern Umbraco using the official Management API — no package to install or marketplace listing required.

Requirements

Before connecting your Umbraco site, make sure you have:

  • An Umbraco 15 or newer site (Umbraco 17 LTS is recommended), reachable from the public internet over HTTPS. API Users with client credentials — which BlogSEO uses to authenticate — were introduced in Umbraco 15, so earlier versions (including 13 LTS) cannot be connected.
  • An API User with Client Credentials (a Client ID and Client Secret). See below to create one.
  • The API User's group needs access to the Content, Media, and Settings sections. The built-in Administrators group works with no extra setup.

Umbraco's Management API only accepts requests over HTTPS. Your site URL must start with https:// — a plain http:// address is rejected before the connection can be tested.

Creating an API User

BlogSEO authenticates with an Umbraco API User using OAuth2 client credentials, so you never share a person's login.

  1. In your Umbraco backoffice, go to Users and click Create → API User (available in Umbraco 15+).
  2. Give it a name (for example, content-publisher) and assign it to a user group that can reach the Content, Media, and Settings sections. The built-in Administrators group is the simplest choice.
  3. Open the new API User, add Client Credentials, and copy the generated Client ID and Client Secret. The secret is shown only once — copy it now.

Umbraco stores the Client ID with an umbraco-back-office- prefix. You can paste either the prefixed or unprefixed value into BlogSEO — the connection handles both.

Connecting BlogSEO to Umbraco

  1. In your BlogSEO dashboard, go to Integrations → Umbraco and click Connect Umbraco.
  2. Enter your Umbraco site URL over HTTPS (for example https://example.com).
  3. Enter the Client ID and Client Secret of the API User you created.
  4. Click Test Connection to verify, then Connect.

The connection test confirms your site is reachable over HTTPS, that the Management API is available (Umbraco 15+), that the credentials are valid, and it warns you if the API User is missing access to the Content or Media sections.

Selecting a document type and parent page

Umbraco stores content as documents of a document type (for example, Blog Post) arranged in a content tree, so after connecting you choose what BlogSEO publishes and where:

  1. On the Umbraco integration page, click Select Document Type.
  2. Pick the document type your articles will be published as (for example, Blog Post).
  3. Pick the parent page in your content tree that new articles are created under (for example, your Blog page).
  4. Save your selection. The integration becomes active once a document type and parent page are chosen.

BlogSEO reads the document type's schema to map its properties automatically — which property holds the body (a Rich Text or Markdown property), the cover image (a Media Picker), the meta description, and tags — so it works even when your properties have custom names. If your site has a single blog-like document type, BlogSEO selects it for you when you connect.

Choosing defaults (optional)

In the configuration dialog you can fine-tune:

  • Body, meta description, cover image, and tags properties — auto-detected from the document type, but you can override which property each maps to.
  • Language — for document types that vary by culture, the language articles are published in.
  • Field mapping instructions — free-text guidance for how BlogSEO should fill any extra properties on your document type (for example, "put a one-sentence summary in the Subtitle property").

You can also set tags per article from the article preview sidebar before publishing.

Publishing content

You have two options for publishing articles to Umbraco:

  1. Auto-publish: enable auto-publish in the Umbraco integration settings, and BlogSEO pushes articles to your site as soon as they are generated.
  2. Manual publish: from the dashboard, select a generated article and click Publish.

BlogSEO handles the publishing details for you:

  • Rich text and tables: articles are converted to clean HTML so headings, lists, links, and tables render correctly in your Rich Text property.
  • Cover image: uploaded to your Umbraco media library (into a Blog Articles folder) and set on the document's Media Picker property.
  • Inline images: uploaded to your media library and referenced from the article body; if an upload fails, the image is linked from its original location instead.
  • Tags and extra fields: tags are set on your Tags property, and any additional properties on your document type are filled by AI from the article (guided by your field mapping instructions).
  • SEO and slug: the name, body, meta description, and a custom URL segment are set on the document.
  • Updates: editing an article in BlogSEO and re-publishing updates the same document instead of creating a duplicate.

Draft mode

When draft mode is enabled, articles are created as Draft documents in Umbraco instead of being published. You can review them in the backoffice and publish them manually when ready.

Controlling the URL slug

To let BlogSEO set a custom URL slug, add a Textstring property with the alias umbracoUrlName to your document type. When present, BlogSEO writes the article's slug there and Umbraco uses it as the page's URL segment.

Without an umbracoUrlName property, Umbraco derives the URL from the document name (the article headline) — publishing still works, the slug just follows the title.

Umbraco Cloud

Umbraco Cloud sites work exactly the same way — create an API User in the backoffice and connect with its client credentials. If you have enabled Management API IP filtering on your Cloud project, allowlist BlogSEO's outbound IP addresses so our servers can reach the API; contact us through the in-app chat for the current list.

Troubleshooting

"Umbraco 15 or newer is required"

API Users with client credentials do not exist before Umbraco 15, so older sites (including 13 LTS) cannot be connected. Upgrade your Umbraco site to 15 or newer — ideally the latest LTS — and connect again.

Connection test fails

  • Use HTTPS: the site URL must start with https://. Umbraco rejects Management API logins made over plain HTTP.
  • Check the credentials: copy the Client ID and Client Secret from the API User's Client Credentials screen. The secret is shown only once — regenerate it if you no longer have it.
  • Check the version: the Management API requires Umbraco 15+.
  • Permissions: the API User's group needs access to the Content, Media, and Settings sections.
  • Firewall / network: make sure your Umbraco site is reachable from the public internet over HTTPS (on Umbraco Cloud, allowlist our IPs if you filter the Management API).

Images not appearing

BlogSEO downloads your article's images and re-uploads them to your Umbraco media library. If the original image URLs are behind authentication or have expired, the upload is skipped. Re-generate or re-upload the image in BlogSEO and publish again.

Articles publish but the URL is the headline, not my slug

Add a Textstring property with the alias umbracoUrlName to your document type (see Controlling the URL slug above). Without it, Umbraco builds the URL from the document name.

For additional support, contact our team through the in-app chat or at support@blogseo.io.

Was this page helpful?