Botpoison
Documentation
Dashboard

Keys

Read the Botpoison docs page "Keys" at https://botpoison.com/documentation/platform/keys.md
and use it to make this change in my project.
Use the stack this project already runs on, and ask me for my keys rather than inventing them.

Every project has two keys: a public key for your pages and a secret key for your server. Both work with every product. Find them on the project's Settings tab in the dashboard.

Public key

The public key starts with pk_. It sits in your page's markup or JavaScript, where anyone can read it. It can only request a challenge for its project, so it identifies the project rather than unlocking anything. It never changes, so published pages keep working.

Secret key

The secret key starts with sk_. Your server sends the same key to every product: to /verify with each Challenge solution, and to /classify with each message. Keep it in your server's environment, never in client code, a public repository or a log line.

Shell
# .env on your server
BOTPOISON_SECRET_KEY=sk_xxxxxxxx

The dashboard shows the key once, when it is issued: copy it then. Botpoison stores only a keyed hash of it, so nobody can read it back later, including us. Afterwards the Settings tab shows its first and last characters, so you can tell which key a server holds, and when it was last used. Lost the key? Reroll it.

Send it as an Authorization: Bearer header, an X-Api-Key header, or as secretKey in the body. If a call to /verify carries more than one, the body key wins, then the bearer token. A call to /classify that carries two different keys fails with a 401. See the Challenge REST API and the Classify REST API.

Rerolling the secret key

Reroll the secret key when it may have leaked, or when someone with access leaves. The public key, the settings and the history stay the same.

  1. Open the project in the dashboard and go to its Settings tab.
  2. Choose Reroll key and confirm.
  3. Copy the new secret key into your server's environment. It is shown only this once.
  4. Deploy, then check one call to each product you use.
  5. Revoke the old key under Previous key once its last use stops moving, or let it run out on its own.
The old key keeps working for 1 hour

After a reroll, every product accepts both keys for 1 hour, so you can deploy the new one without a gap. Then the old key is refused with Invalid secret key. If the key leaked, revoke the old one as soon as the new one is live: a revoked key is refused at once.

Test key

In development, use the secret key test. What it does depends on the product: see Challenge test mode and Classify test mode.