How to Connect Payload CMS, and What Agents Can Change There
Updated
Before You Start#
- Payload 2 or 3, reachable over https.
- For SEO titles and meta descriptions: Payload's SEO plugin (
@payloadcms/plugin-seo), or your ownmetaorseofields on your pages and posts. - API keys turned on for your users collection, or another collection that signs users in (
auth: { useAPIKey: true }). Payload's website template has it off: your developer turns it on in one line. - For redirects and page address changes: Payload's redirects plugin (
@payloadcms/plugin-redirects), with your website serving those redirects as permanent (301 or 308).
Your website must show the fields
SEOmatic fills in fields in Payload. Google only sees an SEO title or description if your website's code reads those fields. Payload's website template does.
Connect Payload#
- In Payload admin, open Users and create a user for SEOmatic that can edit your pages, posts and media.
- On that user, turn on Enable API Key, copy the key, and save the user.
- In SEOmatic, on the Payload CMS row, click Add Connection. Enter Your website, the Payload address (where /admin opens, for example cms.example.com, or its API address) and the API key, then click Connect.
New posts go to your posts collection (or articles, blog, news when that is what you have). You can change it on the connected card. If your users collection has another name, click Users collection has another name? in the form.
No API keys and your developer would rather not turn them on? Click sign in with a user instead in the API key help and enter the email and password of the user made for SEOmatic. Never use your own admin login.
What Your Agents Can Change on Payload#
| Change | What happens | Notes |
|---|---|---|
| Page title | Live | The page's title or name field |
| SEO title and meta description | Live | With Payload's SEO plugin (its meta fields), or SEO fields of your own (a seo group, or metaTitle and metaDescription). Without them: Can't do yet |
| Page text | Live | In pages with one rich text body (Lexical or Slate), and in pages built from layout blocks, where the text inside each block is edited. Images, relationships and blocks inside the text stay exactly as they are |
| Image alt text | Live | On images in your media collection that have an alt field: images in upload fields anywhere on the page and images inside the text |
| New articles | Live | In your blog collection, as a draft or published, as you ask. The featured image goes to your media collection (up to 20 MiB) |
| Redirects | One click Apply | With Payload's redirects plugin (@payloadcms/plugin-redirects), when your website serves its redirects as permanent (301 or 308). Otherwise you get the exact rule to add where your site is hosted |
| Page address (URL) | Live | Only with the redirects plugin: SEOmatic adds the 301 from the old address first. Not for pages in a nested page tree, and not on a site in several languages that share one address field. Otherwise: Can't do yet |
| Canonical, noindex, structured data | Live | Only when your pages have a field for it (for example meta.canonical, meta.noindex or a robots field, meta.structuredData) and your live page shows the value. Otherwise: Can't do yet |
| Other robots settings, excerpts, menus | Can't do yet | Robots settings other than noindex, excerpts and your header and footer menus are not changed |
How SEOmatic Keeps Your Pages Safe
- SEOmatic acts with the access of the user you connected, nothing more.
- Layout blocks: every block keeps its id, and every other block is checked unchanged after saving.
- Text with images or blocks: an edit that would remove, move or change an image, relationship or block inside the text is refused. A page whose text holds something SEOmatic cannot carry (a link to another document in Payload, styled or aligned text) is left alone.
- New articles: the featured image is set on the same image field your posts already use, so SEOmatic needs at least one existing post with an image to learn which field that is.
- Redirects: after adding one, SEOmatic checks the old address on your live site. If it does not redirect, SEOmatic removes the redirect again.
- Page address changes: SEOmatic checks on your live site that the old address redirects to the new one. If it does not, SEOmatic puts the old address back and removes the redirect.
- Canonical, noindex and structured data: if your live page does not show the new value after saving, SEOmatic puts the previous value back. Structured data only goes into an empty field or one holding SEOmatic's own block.
- Languages: on a Payload with several languages, a change lands only in the language of the page's address (for example /fr/...), never in another language.
SEOmatic never publishes someone's draft. A page that only exists as a draft is saved as a draft, and goes live when you publish it. When a published page has unpublished edits waiting, the change waits for you (Needs you). If your website rebuilds after a publish, the change shows once the rebuild is done.
Fix Connection Errors#
| You see | What to do |
|---|---|
| Payload did not accept this API key... | Check that API keys are on for your users collection and that the key belongs to one of its users. Copy the key again. |
| No Payload API answered at... | Use the address where /admin opens. If your Payload uses another API route, enter its full address, for example cms.example.com/cms-api. |
| Signed in, but this user cannot read any collection with pages | Give SEOmatic's user read access to your pages and posts. |
| Signed in, but this user can only read your pages | Give SEOmatic's user permission to update pages and posts. |
Was This Article Helpful?
Still need help?Email contact@seomatic.ai with your site address and a screenshot. A person replies, usually within one business day.


