Personal Access Tokens

Quick setup guide — Simplify API

A personal access token lets a program call the Simplify API on your behalf — a script, a scheduled job, or another system you run — without a browser sign-in and without your password.

The token acts as you. Anything your account is allowed to do, a token of yours can do, unless you deliberately narrow it when you create the token.

1. Before you start

Tokens are personal. You only ever see your own, and another user cannot see or use yours — not even an administrator.

Where to find the page

1. Sign in to Simplify.
2. Click your name in the top-right corner of the header.
3. Choose Profile from the menu. This opens your Settings page.
4. Open the Personal Access Tokens tab, on the row of tabs next to Profile, Password and API Credentials.

Or go straight there: https://simplify.ecgrid.com/app/account/personal-access-tokens

2. Choosing what a token may do

Every token is created with one of two access settings.

Full access — the token can do everything your account can do. Simple, and the right choice when the token drives your own integration end to end.

Custom defined — you pick exactly what the token may do, and the token can do nothing else. Use this for anything you would rather keep narrow: a token that only submits documents, a token handed to a contractor, a token living in a system you do not fully control.

With Custom defined, you choose from a list of your features, each offering three levels:

The levels include each other: choosing Edit also grants Read, and Delete grants all three — you cannot change something you cannot see. On screen this happens automatically as you tick the boxes; through the API you list the names yourself, so include FlowRead alongside FlowEdit.

Separately from that list sits Run transformations through the API (WorkflowExecute), the one permission needed to submit a file to a map and read the result. A token meant only for pushing documents does not need this permission.

3. Rules and limits

Revoking a token frees up its name, so a replacement can carry the same one.

Part 1 — Manage tokens in the web app

4. Create a token

1. Open the page as described in Section 1.
2. Click Generate token.
3. Fill in the form:

   Field	Required	Notes
   Name	Yes	Use something that says where the token is used — Nightly order upload, Partner X sandbox.
   Expiration (optional)	No	Pick a future date, or leave empty for a token that never expires.
   Access	Yes	Full access, or Custom defined and then tick what the token may do.

4. Click Generate.

5. Copy the token immediately

The token is shown once, in a dialog, right after it is created. Copy it and store it somewhere safe before closing that dialog. It cannot be displayed again and there is no way to recover it — if you lose it, revoke the token and create a new one.

A token looks like this:

From then on you only see a short hint such as pat_••••4aI — enough to recognize which token is which, not enough to use.

6. Review your tokens

The list shows:

Open the row menu (…) and choose Info for the full picture, including the exact list of items a custom token is allowed to do.

Two details about this list: Last Used is recorded at most once every few minutes, so on a busy token it can lag slightly behind the real last call. Expired tokens stay on the list for 30 days so you can still see what happened, then drop off. Revoked tokens disappear from the list immediately.

7. Revoke a token

Revoke a token as soon as it is no longer needed, or the moment you suspect someone else has seen it.

1. Open the row menu (…) and choose Revoke — or open Info and click Revoke there.
2. Confirm.

The token stops working immediately and cannot be brought back. Anything still using it starts failing at once, so put the replacement in place first if that matters.

Part 2 — Manage tokens through the API

Everything in Part 1 can also be done from a script. This is useful for rotating a token on a schedule, or for reading which tokens exist from your own monitoring.

8. How these calls authenticate

These endpoints take the same credential as any other API call: either your signed-in session or an existing personal access token (see Section 12). They require no particular permission — being signed in as yourself is enough.

All five endpoints sit under /api/personal-access-tokens:

9. Create a token

The response carries the token itself — the only time it is ever returned:

Write token straight into your secret store. Nothing can read it back afterwards, and it is deliberately kept out of the request logs.

Before offering Custom scopes, you can ask what you are allowed to grant:

Any name outside that list is rejected with Requested scopes exceed your current permissions.

10. List and read your tokens

The list is a paged request, so the parameters go in the body:

Like the screen, this returns your active and recently expired tokens — revoked ones are left out, and expired ones drop off 30 days after expiry. For one token in full, including the scopes of a custom token, ask for it by id:

Unlike the list, this one still answers for a revoked token, with status reading Revoked. Asking for a token that is not yours gives 404 Not Found — the same answer as one that does not exist.

11. Revoke a token

A success is 204 No Content, with no body. The token stops working immediately and cannot be brought back. Revoking a token that is already revoked gives 400 Bad Request — This personal access token is already revoked.

A rotation script therefore runs in this order: create the new token, put it in place and confirm it works, then revoke the old one. Revoking first breaks everything still holding the old token.

12. Authenticate your API calls

Whatever you are calling — the token endpoints above, a document push, or anything else — send the token in the Authorization header, with the word Bearer in front of it:

That is all. There is no separate sign-in step, no session to keep alive and nothing to refresh. The token works on every API endpoint your account can reach, limited further by its own access setting.

13. When something goes wrong

14. Keeping tokens safe

A token is a password with no second step behind it — treat it like one.

• Store it in your system's secret store or an environment variable. Never in source code, a shared spreadsheet, a ticket, a chat message or a screenshot.
• One token per use. A separate token per script or integration means you can revoke one without breaking the others, and Last Used actually tells you something.
• Set an expiration. A token that expires on its own limits the damage of one you forgot about.
• Grant only what is needed. A token used only to push documents needs no WorkflowExecute or edit/delete permissions.
• Revoke instead of reusing. If a token may have been exposed, revoke it and issue a new one; there is nothing to "reset" on an existing token.
• Send it over HTTPS only, and in the header — never in a URL, where it ends up in logs and browser history.
• Review the list from time to time and revoke anything you no longer recognize.