Using Tokens

An agent token lets a program act on GeoHazardWatch as you, without knowing your password. Use one when a script, an AI assistant, or another system needs to read or write pages on your behalf.

A token is a delegation of your own authority. It can never do anything you could not already do yourself, and everything it does is recorded against both your account and the token's name.

Why not just give the program your password

A password is all-or-nothing and permanent. A token is not:

• Limited — you choose what it may do. A token for creating pages cannot delete them.
• Short-lived — it expires within a day. A leaked token stops working on its own.
• Revocable — you can switch one off immediately without changing your password.
• Traceable — every page it creates or edits is attributed to that token by name, so you can tell later which program made a change.

Handing over a password gives up all four.

Before you start

Tokens are off by default. If you do not see the Agent API Tokens section described below, an administrator needs to enable them first — see Server Management.

Creating a token

1. Sign in and open your Profile Page.
2. Find the Agent API Tokens section and choose New.
3. Fill in three things:

1. Choose Create.

Choosing permissions

Pick the narrowest option that works. You can always create a second token later.

Copy the token immediately

The token is shown once, when you create it. It is not stored anywhere you can read it back — only a scrambled form is kept, so nobody, including an administrator, can recover it afterwards.

Copy it straight into wherever the program keeps its settings. If you lose it, revoke it and create another; there is no way to look it up.

A token looks like ngdp_at_ followed by a long string of characters.

Giving the token to a program

The program sends the token with each request, in a header:

Authorization: Bearer ngdp_at_your-token-here

Most tools have a field for this — often labelled "Bearer token", "API token", or "Authorization header". Anything that can call a web API can use one.

Treat it like a password

A token is a working credential for your account, within the limits you set.

• Do not paste it into a page, a chat message, or an email.
• Do not commit it to a code repository.
• Keep it in the program's own configuration or secret storage.
• If you think it has been seen by anyone else, revoke it. That takes effect immediately.

Seeing and revoking your tokens

Your Profile Page lists every token you have, with its name and when it expires. Each has a control to revoke it.

Revoking is immediate — the next request using that token is refused. Nothing else you own is affected, and your password is unchanged.

When tokens expire

Every token expires within a day at most. This is deliberate: a credential that lives forever is one that leaks quietly and keeps working.

A program that runs continuously therefore needs a new token each day, created here while you are signed in. There is no way for a program to renew its own token — that is the point, since anything able to renew a credential indefinitely is close to a permanent one.

If a program stops working and reports an authorisation failure, an expired token is the first thing to check.

Limits

• A token lasts at most 24 hours.
• You may have up to 10 active tokens at once. Revoke ones you no longer use.
• A token can never exceed your own permissions. If your access changes, so does what your tokens can do.

Related

• Profile Page — where tokens are created and revoked
• User Roles and Permissions — what your account may do, which bounds every token you create
• Server Management — enabling tokens, for administrators