Create a personal access token

What it is

A personal access token — the dashboard calls it an API key — is a long-lived credential your own code uses to call Agentency as you. It is the supported way for a server job, a CMS plugin, or a scheduled script to talk to the API.

Three properties define it:

• Scoped. You choose exactly what the key may do when you create it, and that set can never be widened afterwards.
• Time-limited. Every key carries an absolute expiry, chosen at creation.
• Shown once. The secret is displayed a single time, in the dialog that creates it. Agentency does not keep a readable copy, so it cannot be shown again.

A key is not your dashboard session. Creating or revoking a key never signs your browser out, and your browser session is never a valid credential for a server.

When you would use it

Create a key when a machine needs to act on your account: pushing knowledge from a CMS, installing the widget from a site plugin, running a nightly sync, or querying your own chatbot from a backend service.

Do not create one to put in a web page. Anything in browser JavaScript is readable by anyone who opens developer tools. The widget has its own public token and allowed-domain list for exactly this reason — see Embed the website widget.

Where to find it

Open Dashboard → Settings → Developer. This tab is visible only to the owner of the account you are working in — see Why only the owner sees Billing.

Steps

1. Confirm you are in the account you own. Developer is hidden inside a workspace you merely joined.
2. Open Dashboard → Settings → Developer.
3. Choose Create API key.
4. Name it after the system that will hold it, not after yourself — wordpress-production, nightly-catalog-sync. In six months this name is the only clue you will have about what breaks if you revoke it.
5. Tick the smallest set of permissions the integration needs. See Choose token scopes.
6. Choose an expiry. The presets are 30, 90, and 365 days, plus a No expiry option that is really a very distant fixed date rather than a key that lives forever.
7. Create the key. The secret appears once — copy it or use the download button, and put it straight into your secret manager or your deployment's environment configuration.
8. Confirm you have stored it, then close the dialog.
9. Verify the new row in the table, then make one real call to prove the key works before you wire the rest of the integration.

What you will see

The Developer tab is a table of keys with Name, Scopes, Created, Last used, Expires, and an action to revoke. Above it sits a notice reminding you to treat keys like passwords.

The create dialog asks for a name, a set of permission checkboxes, and an expiry, and then reveals the secret with copy and download buttons and an explicit acknowledgement before you can dismiss it.

Below the table is the Knowledge Ingest API reference — the same documentation shown inside the Add Knowledge drawer, with a copyable endpoint, a parameter table, and ready-made curl, JavaScript, and Python snippets. See API reference on the Developer tab.

Using the key

Send it as a bearer token on every request:

curl -s https://api.example.com/chatbots \
  -H "Authorization: Bearer $AGENTENCY_TOKEN" \
  -H "Accept: application/json"

Replace the host with your own API base — see API host — no /api prefix, because there is no /api prefix and getting that wrong produces a 404 that looks like an auth problem.

The Last used column updates as the key is exercised, which makes it the quickest way to answer "is anything still using this key?" before a clean-up.

Choosing an expiry sensibly

Short expiries are only a security win if you actually rotate. A 30-day key that nobody renews takes your integration down on day 31 in the middle of a Tuesday.

A reasonable default:

• 30 or 90 days when you have a rotation process, or during development.
• 365 days for a stable production integration with a calendar reminder attached.
• No expiry only when the key lives somewhere you fully control and you have another way of noticing that it should be retired.

Whichever you choose, write the renewal date somewhere a human will see it. Expiry is not negotiable after the fact — an expired key must be replaced, not extended.

Keeping the secret safe

• Store it in a secret manager or your platform's environment configuration. Never in the repository, never in a ticket, never in a chat message.
• Give each system its own key. Shared keys cannot be revoked without an outage for everyone.
• Give each key the narrowest scopes that work. A key that only installs a widget should not be able to edit chatbots.
• Revoke keys you are not using. The Last used column tells you which those are.
• If a key leaks, revoke it first and investigate second — see Rotate or revoke a key.

Limits and plan notes

Key management is owner-only, and a self-service key can never mint another key. That is deliberate: if a key could create keys, the scope model would only be one request deep.

Self-service keys also cannot manage team members or read and change the owner's own profile, phone, or two-factor settings. Those surfaces are reachable from a signed-in browser session only.

A key always acts on its owner's account. There is no equivalent of the dashboard account switcher for a token.

Key creation supports an idempotency key on retry, so a double-submitted create request replays the first result instead of producing two keys.

Common problems

I closed the dialog without copying the secret.

It cannot be recovered. Revoke that key and create another — an uncopied key is a row in the table doing nothing.

Developer is not in my Settings.

You are not the owner of the account you are currently in. Switch back to your own account.

The key works locally but not in production.

Compare the exact secret in both environments — truncation on paste is the usual cause — and confirm the production host is the API host and not the dashboard host.

A call returns 403 with an insufficient-scope error.

The key is valid but lacks the scope that route requires. Scopes are fixed at creation, so mint a new key with the missing permission.

Can I share one key with my whole team?

You can, but do not. When one person leaves, you either revoke and break everyone, or leave a live credential with a former colleague.

Does revoking a key sign me out of the dashboard?

No. Key revocation and browser sessions are entirely separate.