API tokens and scopes

An API token lets your code or your agent call Wayfern as you. Each token carries scopes that decide which APIs it can call. This guide shows how to create a token, pick its scopes, set an expiry, and revoke or delete it.

What a token is

A token is wf_ followed by 43 characters. Wayfern stores only a hash of it, so the full token is shown once, when you create it. Store it in a secret manager at once. Send it in the Authorization header:

curl https://api.wayfern.com/api/search/engines \
  -H "Authorization: Bearer $WAYFERN_API_TOKEN"

This call is free and needs the search scope, so it is a quick way to test a new token.

A token belongs to your user account, not to a project. Web Data, Search and Captcha calls bill your account. Operation calls bill the owner of the operation’s project. Browser sessions use link tokens, which are separate from API tokens. See Share a browser link.

Scopes

Scope	Allows
search	The Search API under /api/search
captcha	The Captcha API under /api/captcha
mcp	The MCP server at https://api.wayfern.com/mcp
web	The Web Data API and Operations under /api/v1
fingerprint	Fingerprint and running-profile routes. Service accounts only.

A new token gets search, captcha, mcp and web when you do not choose. fingerprint is never a default. Two more scopes, admin_workflows and admin, are for Wayfern administrators only.

You cannot change the scopes of a token after you create it. To change them, create a new token and revoke the old one.

A token without the scope a route needs gets 401 with a message such as API token is missing the "web" scope.

Create a token

In the dashboard, open API Tokens and select New token. Enter a name, tick the scopes and set an expiry date if you want one. Tick the box to confirm that you stored the token, then close the dialog.

The token routes under /api/tokens accept a signed-in dashboard session, not an API token. A wf_ token on these routes gets 401. With a session token, the call is:

curl -X POST https://api.wayfern.com/api/tokens \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly crawler",
    "scopes": ["web"],
    "expiresAt": "2027-01-31T00:00:00.000Z"
  }'

Field	Rules
name	Required, 1 to 255 characters
scopes	At least one, no duplicates. Default: search, captcha, mcp, web.
expiresAt	Optional ISO-8601 time in the future. Without it, the token does not expire.

The answer is 201 with token, the stored record, and plaintext, the secret. The record has id, name, tokenPrefix, scopes, lastUsedAt, expiresAt, revokedAt and createdAt. There is no limit on the number of tokens.

Expire, revoke and delete

• An expired token stops working at its expiresAt. You cannot extend it.
• POST /api/tokens/:id/revoke stops a token at once. The record stays in the list with revokedAt set.
• DELETE /api/tokens/:id removes the record. The answer is 204.
• GET /api/tokens lists your tokens without their secrets. lastUsedAt updates at most once a minute.

A revoked, expired or deleted token gets 401 with Invalid, revoked, or expired API token. A token also stops working when its owner account is disabled.

import os

import requests

auth = {"Authorization": f"Bearer {os.environ['DASHBOARD_JWT']}"}
base = "https://api.wayfern.com/api/tokens"

tokens = requests.get(base, headers=auth, timeout=30)
tokens.raise_for_status()
for token in tokens.json()["tokens"]:
    if token["revokedAt"] is None and token["lastUsedAt"] is None:
        print("never used:", token["name"], token["tokenPrefix"])

Use one token per job or per agent, with only the scopes it needs. Then you can revoke one job without stopping the others.

Service accounts

A service account is an account that a Wayfern administrator marks for integrations. You cannot make one yourself.

• It can create tokens with the fingerprint scope, for the routes under /api/v1/fingerprints. Other accounts cannot use these routes.
• Plan caps on open pages and seats do not apply to it.
• Its usage is recorded, but no credits are debited.

See Authentication and Tokens and accounts for the reference.