Skip to content

Connect a Site

Grafida talks to your Joomla! site through its Web Services (REST) API. Your site needs an active API token, and Grafida needs the site's address and that token.

1. Check the Web Services plugins

In your site's administrator interface, open System → Plugins and filter by the Web Services type. Publish at least the plugins for Content, Media, Tags and Users. Without them the API answers, but has nothing Grafida can use.

While you are there, check that the User — Joomla API Token plugin is enabled: it is the one that draws the token field in the next step.

2. Get a Joomla API token

  • Log into your site and open your own user account's edit page. In the administrator interface that is the User Menu in the top right, then Edit Account.
  • Open the Joomla API Token tab.
  • Set Active to Yes and save.
  • The page now shows a Token field. Copy it.

Treat that token exactly as you would a password. Whoever holds it can act on your site as you, it does not expire on its own, and it cannot be limited to one task.

Warning

Switching Active off and back on mints a new token. The old one stops working the moment you do, and any copy of it — in Grafida, or anywhere else — has to be replaced.

If you are not a Super User, ask whoever is to confirm your account has the core.login.api permission. Without it, a token from this account cannot authenticate to the API at all, whatever the profile page shows.

3. Add the site in Grafida

  • Open Sites and press Add site.
  • Title — anything that helps you recognise it, such as "Company blog". It is local to Grafida and never sent anywhere.
  • URL — your site's base address, for instance https://www.example.com. Leave off /administrator, /api and any language code such as /en; Grafida works out the rest of the address for itself. It must be an HTTPS address with a certificate your system trusts. If you leave the https:// off, Grafida adds it; if you type http:// explicitly, it is refused rather than quietly rewritten — see HTTPS is required.
  • API token — paste what you copied above.
  • Leave the remaining fields at their defaults for now. Sites explains each one.
  • Press Save.

4. Test the connection

Test connection checks the address and the token against the live site and reports what it found. It works on a saved site, so save first — a brand-new site form will tell you as much rather than testing something that does not exist yet.

A successful test reports the API address it found. If it fails, Connection Troubleshooting explains what each message means.

Note

You never type the API address yourself. Grafida tries the three forms a Joomla site can serve it from, in order, and remembers the one that answered.

5. Choose the active site

Most of Grafida works on one site at a time. Back on the Sites list, press Set as active site on the row you want; that is what gives the Articles and Media screens something to show. Pressing the row itself opens the site's form instead — the two are different actions.

Connecting more than one site

Repeat the steps above for each site. Every site keeps its own token, its own cached categories, tags, access levels, languages and custom fields, and its own media settings. Nothing is shared between them except the application itself.