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 (
auth: { useAPIKey: true }). Payload's website template has it off: your developer turns it on in one line.
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) 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 |
|---|---|---|
| Title | Live | The page or post title |
| SEO title and meta description | Live | Through the SEO plugin's meta fields |
| Page text and internal links | Live | In a page's rich text field (Lexical or Slate). Pages built from layout blocks, and text holding images or blocks, keep their text |
| Image alt text | Live | On the image in your media collection |
| New posts | Live | In your blog collection |
| URL, canonical, noindex, structured data | Not yet | The SEO plugin has no field for them |
Drafts stay drafts: a change to a draft is saved to the draft. When a published page has unpublished edits waiting, SEOmatic waits too, so it never publishes someone's draft. 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.