Keys and test environments: site key and verification secret

What there is to know: site key, secret, evaluation key

Site key

32 alphanumeric characters. Public: it goes in the data-site attribute of the tag. The dashboard shows it under the name “Identifiant public du site” (public identifier of the site).

Verification secret

64 alphanumeric characters. It goes in the secret field of /v1/siteverify, on the server side only. In the dashboard, it is a key of use “Vérification serveur” (server-side verification).

The same secret is used, without an Authorization header, to report the real outcome of an attempt through /v1/feedback (see verification). A test secret receives there the response of a report taken, without anything being recorded.

Evaluation key

64 characters too, of use “Évaluation (kit signé)” (evaluation, signed kit). It is for the Node SDK, which will be published on npm with its documentation; it is not published yet. It is not a verification secret: siteverify refuses it with invalid-input-secret, as does /v1/feedback without an Authorization header.

Create, copy, revoke

• In the “Clés” tab of the site, “Créer une clé” (create a key): choose the environment (Production or Test) and the use. The key is shown only once, when it is created. Copy it then into your secrets manager or your environment variables.
• The list then shows the first four characters of each key, its creation date, its last use and its state. If you lose a secret, create another one.
• “Révoquer” (revoke) asks for a confirmation. A revoked key is refused within the 10 seconds that follow (Antisy keeps the valid keys in memory for that long): the verification then answers invalid-input-secret.
• Antisy never logs a secret beyond its first four characters.

Changing a secret without an interruption

1. Create a new verification secret, without revoking the old one.
2. Deploy it on your server.
3. Check that it works: the “dernier usage” (last use) of the new key is updated.
4. Revoke the old one.

If a secret has leaked, revoke it without waiting: a revoked secret is of no use any more, and you create another one.

Test keys

For continuous integration or local development, Antisy provides dummy keys and tokens.

Dummy site keys

Two fixed public keys, with the shape of a real site key. Each one gives the verdict of its name.

• allow: TestAllow00000000000000000000000
• deny: TestDeny000000000000000000000000

Test secret

A key created with the “Test” environment and the “Vérification serveur” use. A site holds at most 2 at a time. It is not counted in the statistics. The test keys of the whole organisation, all sites together, share 1,000 calls per day (UTC day) and, to date, 2,500 per month (UTC month). Beyond either: 429, until the next midnight UTC or until the first of the next UTC month.

In a development page

Put a dummy site key in the data-site attribute of the tag. The script goes through its whole path, as with a real key, and the antisy-token field as well as antisy.token() receive the fixed token of that key. Your server verifies it with a test secret and obtains the verdict of the dummy key.

• No host name to declare: a dummy key has none, and, to date, Antisy does not check the origin of the page for it. localhost, 127.0.0.1 or a staging server over HTTPS receive the same token. Your production site keeps its list of names, without localhost.
• The token is always the same, and public: it says nothing about the visitor. What the development page shows is that the script runs: an incomplete CSP policy, for example, shows up there before production.

Without a browser (continuous integration)

First you obtain a fixed token by submitting on a dummy site key, then you verify it with a test secret. The submission expects neither an attempt token nor a measurement from the browser: any envelope starting with ae2. will do, and the response carries the token in clear.

# 1. A test token: the dummy site key “allow”, any envelope.
TOKEN=$(curl -sS https://api.antisy.com/v1/collect \
  -H 'content-type: application/json' \
  -d '{"site":"TestAllow00000000000000000000000","envelope":"ae2.test"}' \
  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

# 2. Its verification, with a test secret (through standard input, not as an argument).
printf 'secret=%s' "$ANTISY_TEST_SECRET" | curl -sS https://api.antisy.com/v1/siteverify \
  -d @- \
  --data-urlencode response="$TOKEN"

The response carries the verdict of the dummy key, the test_key flag, and nothing in challenge_ts, hostname and action, whether the fixed token comes from the CI or from a page: no real token was submitted.

{"success":true,"verdict":"allow","flags":["test_key"],"error-codes":[],"challenge_ts":null,"hostname":null,"action":null,"event_id":"evt_…"}

• With a production secret, a fixed token is only an unknown token: invalid-input-response. No real traffic can therefore get through with them.

Never put a test key into production

The fixed tokens are public. With a test secret, anyone can send the “allow” token and be accepted: a bot gets through. A test key put into production by mistake therefore lets bots through, without visibly breaking anything.

• The dashboard marks each test key “Test”, in the list as at creation, with this warning.
• When a test key receives traffic that looks like real traffic, Antisy writes to the alert address of the account (the “Adresse des alertes” setting), at most once a week. Without an address recorded, no message is sent.
• Since no prefix tells them apart, keep your test secrets in environment variables named as such, and separate from those of production.
• Do not leave a dummy key in data-site in production: with the production secret of your site, each fixed token returns invalid-input-response, so each submission is refused.

For what comes next, see server-side verification.