Personal access token (PAT) – what it is and how to use it#
What is a personal access token (PAT)?#
A personal access token (PAT) is a long random string that serves as an alternative to your password for accessing the Mergado API. The token represents you and your permissions – when you give it to someone (or some application), they can perform actions in Mergado on your behalf within the scope you’ve granted to the token.
Unlike a password, a PAT:
- Has a limited scope – you choose exactly what the token can do (e.g. only read projects, not delete them).
- Has an optional expiration – you can set when the token stops working.
- Can be revoked at any time without having to change your password.
- Cannot be used to change account settings (password, email, billing) – those still require a standard login.
- Does not expose your password to a third party, even if you share the token.
A PAT is intended for access to the Mergado Editor API. It cannot be used to sign in to other Mergado services (Mergado Forum, Mergado Store, etc.).
When will I need a PAT?#
Typical scenarios:
- Connecting Mergado with AI agents such as ChatGPT, Claude or Cursor via the Mergado MCP server. See the article Connecting Mergado with AI agents for the full guide.
- Custom scripts and automation – e.g. scheduled data exports, bulk project edits, integrations with internal systems.
- Development and testing of your own applications on top of the Mergado API.
- Connecting with no-code tools like Zapier, Make, n8n or Gumloop.
How to generate a PAT#
-
Sign in to Mergado Editor.
-
In the top-right corner, click your profile → API and Access.
-
Click the + Create token button.
-
Name the token with something that tells you where it’s used – e.g. “Claude Desktop”, “Accounting export script”. When you manage your tokens later, the name is the main thing telling them apart.
-
Set the token’s validity. Options:
- 7 days
- 30 days
- 90 days
- 365 days
- Never (the token will remain valid until you manually revoke it)
For tokens used in automation we recommend setting a specific expiration (e.g. 90 days) – regular rotation reduces the impact of a potential token leak. For development and testing a short validity (7 days) is enough.
-
Select permissions (scopes) – see Permissions.
-
Click Create.
-
Copy the token and store it in a safe place (password manager, encrypted file). Once you leave the page, the token will not be shown again – if you lose it, you’ll have to create a new one.
The token has the prefix mergado_pat_ followed by 60 random characters, e.g. mergado_pat_aec7bb21ff4b2c09b156cd3130b4eef0daf69ea2e1e0d62c23472626aa7e72314fdbb53896b2fd8046c5.
Tip: in the token list you’ll see a token preview in the format
mergado_pat_***8046c5, where the last 6 characters match the suffix of the actual token. This lets you quickly identify which token is which without having the full token on hand.
The token is sensitive – treat it like a password. Anyone with the token has the same permissions in Mergado as you do, within the granted scopes.
Permissions (scopes)#
When creating a token you select specific permissions via checkboxes. Permissions are grouped into logical sections (User, E-shop, Project) so you can navigate them more easily.
Recommendation: grant the token only the permissions the application actually needs. For example, if a script only reads data from a project, it doesn’t need write or delete rights. This is known as the principle of least privilege.
User#
Permissions related to your user account and information about you.
| Permission | What it allows |
|---|---|
| Read user data | Access to user information – name, username, email, registration date, etc. |
| Read user’s e-shops | View the list of e-shops the user has access to (as owner, reader or writer) and their details. |
| Read user notifications | Read the user’s notifications – system messages as well as messages from other applications. |
| Send notifications to user | Send notifications to the user (email and frontend notifications). |
| Read user’s enabled extensions | Access to the list of extensions enabled for the user. |
E-shop#
Permissions for the data of a specific e-shop.
| Permission | What it allows |
|---|---|
| Read e-shop data | Access to e-shop information – name, domain, number of exported items, users with access, etc. |
| Read e-shop’s projects | Access to all projects (exports) of the e-shop and their basic information. Does not include access to rules, queries, elements, etc. |
| Read data of services connected via Keychain | Read data from services connected via Keychain (e.g. Heureka, Google Ads…). |
| Edit data in services connected via Keychain | Write and edit data in services connected via Keychain. |
| Read e-shop statistics | Access to e-shop statistics. Statistics must be collected in advance – requires data to be filled in via Keychain. |
| Read e-shop statistics sources | Access to the list of sources from which statistics are collected. |
| Read e-shop Google Analytics | Read Google Analytics data for the e-shop. The user must first grant permission via Keychain. |
| Read e-shop notifications | Read notifications sent to members of the e-shop, including system messages. |
| Send notifications to e-shop | Send notifications to members of the e-shop. |
| Read e-shop’s enabled extensions | Access to the list of extensions enabled for the e-shop. |
Project#
Permissions for individual projects (exports) within an e-shop. This is the largest group – a project contains rules, queries, products, statistics, etc., and each layer has its own permissions for read and write.
| Permission | What it allows |
|---|---|
| Read project data | Access to basic information about the project – name, feed URL, number of exported items, etc. |
| Edit project data | Edit the project. Does not include creating rules, queries, elements, etc. |
| Read elements | View the project’s elements – name, visibility, and other properties. |
| Edit elements | Create, edit, and delete elements in the project. |
| Read queries | Read queries in the project. Queries are created by the user or by an application. |
| Edit queries | Read, delete, and create queries. Queries can then be used to filter products. |
| Read rules | View all rules in the project. |
| Edit rules | Delete, edit, and create new rules in the project. |
| Read variables | View the project’s variables – name, type, and other information. |
| Edit variables | Delete, edit, and create variables in the project. |
| Read project products | View the project’s products. Sufficient also for filtering products via queries. |
| Write to project products | Delete, edit, and create products in the project. |
| Read project statistics | Access to project statistics and advanced analytics. |
| Read project Google Analytics | Read GA data filtered by the project’s output format (e.g. only Heureka data). |
| Read project processing history | View completed tasks – import from XML, rule application, export to XML (including automatic ones). |
| Trigger new project processing | Trigger tasks – import from XML, rule application, export to XML. |
| Read feed audits | Read the results of the project’s XML feed audit – issues found, missing elements, etc. |
| Trigger feed audits | Run a new validation (audit) of the project’s XML feed. |
| Read project history | Access to project logs – completed tasks as well as downloads of the output XML feed by third parties. |
| Read project’s enabled extensions | Access to the list of extensions enabled for the project. |
For developers: the technical names (IDs) of individual scopes in the API format (e.g.
project.rules.write) can be found in the OAuth scopes API documentation.
In the token list, each row shows the number of granted permissions; clicking Show expands them as tags.
How to use the token#
The token is sent in the HTTP request header as a Bearer token:
Authorization: Bearer <your-token>Example API call via curl:
curl -H "Authorization: Bearer mergado_pat_..." \
https://api.mergado.com/v1/meThe full description of all endpoints is in the API documentation:
- API reference: api-docs.mergado.com
- Authorization guide: mergado.github.io/docs/api/authorization.html
Security and token management#
Do#
- Store the token in a password manager or in an encrypted configuration (e.g. environment variable, secret manager).
- Create a separate token for each application/integration, with its own name. This makes it easy to revoke a specific integration without affecting others.
- Grant the token only the permissions it needs (principle of least privilege).
- Regularly review your active tokens and revoke any you no longer use.
- For tokens used in automation, set the validity to 90 days and rotate the token periodically.
Don’t#
- Don’t commit tokens to Git or any other repository. If it happens by mistake, revoke the token immediately – Git history is publicly accessible even after the file is deleted.
- Don’t send the token via email, Slack, Teams or other chat applications in plain text.
- Don’t share one token across multiple people or applications.
What to do if the token is compromised#
If you suspect that your token has fallen into the wrong hands (e.g. accidentally published in a repository or screenshot, suspicious activity on the account):
- Immediately go to API and Access and revoke the token (trash icon in the list).
- Create a new token and update it in all integrations where it was used.
FAQ#
I lost my token, what now?#
We don’t show the token again. Create a new one and update it in the application where it was used. We recommend revoking the old token so it can’t be misused if someone later finds it.
How many tokens can I have?#
The number of personal access tokens per user is currently not limited. However, we recommend creating a separate token for each integration – they are easier to manage, and if needed, you can disconnect a specific integration by revoking a single token.
How long is the token valid?#
As long as you set when creating it – 7, 30, 90, 365 days, or Never. The current expiration date is shown in the token list in the Expires column. Once expired, the token stops working and you have to create a new one.
The API returns 401 Unauthorized. What now?#
- Make sure the token is copied in full and without leading/trailing spaces.
- Check the header format:
Authorization: Bearer <token>(the wordBeareris followed by a space). - The token may have been revoked or has expired – check the Expires column in the token list.
- If the token is missing from the list entirely, it has been deleted – create a new one.
The API returns 403 Forbidden. What now?#
The token is valid but does not have permission for the given action. Check its permissions in the token list (Permissions column → Show) and, if needed, create a new token with expanded scopes. An existing token cannot be expanded – for security reasons you have to create a new one.
Can I use the token to sign in to Mergado Forum or Mergado Store?#
No. A PAT is intended exclusively for the Mergado Editor API. For other Mergado services, sign in normally using your Mergado account.
Can I use a PAT in an application I provide to my clients?#
No. A PAT represents a specific user. If you’re developing an application that will be used by Mergado customers, use the OAuth flow instead – each user authorizes the application under their own account. See the API documentation for details.
Related links#
- API and Access – manage your personal access tokens
- Connecting Mergado with AI agents (ChatGPT, Claude, Cursor)
- API reference: api-docs.mergado.com
- Authorization guide: mergado.github.io/docs/api/authorization.html