Authentication

Authenticate REST requests and MCP calls with an account token.

REST resource requests and MCP calls require a token. The OpenAPI schema is public. A token grants access to the active brands owned by its account.

Issue a token

After signing in, open Settings → API. Give the token a name that identifies its use, such as “weekly report”, then select Read or Read and write.

An account may hold five active tokens at a time.
Manage tokens in the dashboard. The public API cannot issue or revoke them.
Copy the token when it appears. SearchSeal saves its hash and a short prefix, not the full secret.
All plans include REST and MCP. Access requires an unsuspended account with an active subscription, a valid trial or prelaunch access.

Choose a scope

Scope	Access
`read`	Read authenticated REST resources and call MCP read tools.
`write`	Includes `read` access. Also add, archive or restore questions, and accept, dismiss or complete fixes.

Choose read for integrations that only retrieve data. Neither scope exposes scan controls, Google or Bing connections, brand or question deletion, or reopening fixes. Manage these through the dashboard.

Protect your token

Store the secret in a secret manager or an environment variable.
Keep it out of source control, logs and request URLs.
Send authenticated requests from server-side code.

Terminal

export SEARCHSEAL_TOKEN="<token>"

Send the authorization header

Use the Authorization header and Bearer scheme for both REST and MCP. Request GET /account to verify the token and read its scope.

Token check

curl --request GET \
  --url https://searchseal.com/api/v1/account \
  --header "Authorization: Bearer $SEARCHSEAL_TOKEN"

MCP authentication currently uses personal access tokens. See the setup guide for MCP.

Resolve token errors

Missing, unrecognized or revoked tokens receive 401 unauthorized. With a valid token, 403 forbidden means the account is suspended, lacks access, or the requested operation needs write scope. Read message for the cause. MCP returns forbidden as a tool error when a read token attempts a write operation.

403 response

{
  "message": "This token is read-only. Create a write token in Settings.",
  "code": "forbidden"
}

Resolve the reported cause before sending the request again.

Rotate or revoke a token

Remove a token through Settings → API. Subsequent requests will reject it. For routine rotation, issue a replacement, update your integration, then revoke the previous token.

Revoke an exposed token immediately. Contact support@searchseal.com for help, without including the secret.

Try an authenticated request in the quickstart.