Webhook Relay access tokens: permissions and subscription scopes

Webhook Relay access tokens are individually revocable key-and-secret credentials for relay agents, the CLI, REST API and Model Context Protocol (MCP). Each token has two separate controls: a permission role for API actions and subscription scopes for bucket or tunnel streams. Restrict both controls to give each workload only the access it needs.

Create and manage credentials on the Access Tokens dashboard. The secret is displayed only once and cannot be recovered later.

Choose the right credential

Prefer one standalone token per deployment or integration. A descriptive name such as payments-forwarder-prod makes ownership, audit and rotation clearer.

Create a least-privilege token

1. Open Access Tokens in the dashboard.
2. Select Create Standalone Token.
3. Enter a recognizable Name.
4. Choose the lowest API permissions role the workload needs.
5. Enter its allowed Bucket subscriptions and Tunnel subscriptions. Use !none for a subscription type the workload does not use.
6. Select Create token, then copy both the key and secret before closing the dialog.

For example, a forwarding agent that only receives payment webhooks could use:

A REST-only reporting integration can use Viewer with both subscription fields set to !none. A tunnel agent can do the reverse: set bucket subscriptions to !none and restrict tunnel subscriptions to its tunnel name or host.

Permissions and scopes are different

Token permissions and subscription scopes protect different operations:

This distinction is intentional. A Viewer token can subscribe to an allowed bucket because receiving that event stream is governed by the bucket scope, not by write permission. Conversely, a Member token with bucket scope payments-prod may still manage other buckets through the API; the scope only limits subscriptions.

Permission roles

New standalone tokens created in the dashboard default to Viewer. Token roles use the same permission model as organization member roles:

Owner is not assignable to a token. No standalone token can create, update or delete other tokens, regardless of role. A token also cannot create a browser session, refresh into a session credential or gain platform-administrator access.

In an organization, a token never expands its creator's access. Webhook Relay checks both the member's current organization role and the token role, and the more restrictive permission wins. A member can only issue a role that their own role is allowed to grant.

Bucket and tunnel subscription scopes

Scopes accept comma-separated identifiers and * wildcard patterns.

Bucket scopes match a bucket name or ID:

payments-prod
payments-*
f71b350b-92de-4c66-a249-b4c543fc50cb

Tunnel scopes match a tunnel name, group, host or ID:

customer-demo
production-*
demo.example.com

The important defaults are:

Empty means unrestricted to preserve compatibility with existing tokens. It does not mean deny all. If !none is present beside another identifier or pattern, !none wins and the entire subscription type is denied.

Authenticate the relay CLI

Store the key and secret in the CLI's native credential storage:

relay login -k YOUR_TOKEN_KEY -s YOUR_TOKEN_SECRET
relay bucket ls

For containers and CI/CD, provide the credentials as environment variables instead:

export RELAY_KEY=YOUR_TOKEN_KEY
export RELAY_SECRET=YOUR_TOKEN_SECRET
relay forward --bucket payments-prod http://localhost:8080/webhooks

The CLI and SDK use HTTP Basic authentication for management API calls, with the token key as the username and the secret as the password:

curl --user "$RELAY_KEY:$RELAY_SECRET" \
  https://my.webhookrelay.com/v1/buckets

Do not pass the standalone token secret as a bearer token. APIs that document a single sk-whr… bearer value use the main account API key instead of a standalone key-and-secret pair.

Create a token through the REST API

Use the main account API key to bootstrap a standalone token. This example creates a read-only token for payment-bucket subscriptions and explicitly disables tunnels:

export WEBHOOKRELAY_API_KEY='sk-whrm-…'

curl --request POST \
  --user "whr:$WEBHOOKRELAY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "payments-forwarder-prod",
    "api_access": "enabled",
    "permissions": { "role": "viewer" },
    "scopes": {
      "buckets": ["payments-prod"],
      "tunnels": ["!none"]
    }
  }' \
  https://my.webhookrelay.com/v1/tokens

The response contains key and secret. Save the secret immediately; list and update responses never return it.

For backward compatibility, permissions is optional when creating a token through the API. Omitting it creates a legacy full-access token, while omitted or empty subscription scopes allow all subscriptions. Always send an explicit permission role and both scope arrays for a new least-privilege token.

PUT /v1/tokens/{id} treats the two scope arrays as the token's complete subscription configuration. Always send both scopes.buckets and scopes.tunnels; an omitted or empty scope becomes unrestricted. Omitting permissions on an update preserves the token's current permission state, which allows older API clients to update names or scopes without silently changing access roles.

See the API reference for the token endpoints and schemas.

API access switch

The API access switch is separate from roles and scopes:

• Enabled allows REST and MCP authentication, subject to the token's permission role.
• Disabled blocks general management API use but leaves the credential available for forwarding and tunnel connections. Relay agents may still resolve their bucket configuration and report delivery results.

Configure the bucket, input and internal output before disabling API access. The relay CLI can connect to an existing forwarding configuration, but it cannot use an API-disabled token to create or change that configuration.

Change, rotate or revoke a token

On the Access Tokens page, select a permission or scope value to edit it. Use the API access switch to disable management API calls, or open the token's action menu and select Delete to revoke the credential completely.

Allow up to five minutes for a change or deletion to reach every server and already-connected agent. Long-lived forwarding, WebSocket and tunnel connections periodically revalidate their credentials; a revoked token or changed subscription scope disconnects the old connection and requires the agent to reconnect under the current policy.

To rotate safely:

1. Create a replacement token with the same or narrower access.
2. Update one workload with the new key and secret.
3. Confirm the workload reconnects and operates normally.
4. Delete the old token.

Because tokens do not expire automatically, schedule rotation according to your security policy and revoke credentials immediately when a secret may have been exposed.

Security checklist

• Create one token per agent, service, environment or CI/CD workflow.
• Start with Viewer, then add only the API access the workload proves it needs.
• Set every unused subscription type to !none; do not leave it empty.
• Store secrets in a secret manager or the relay CLI credential store, never in source control or logs.
• Use the token name and last-used timestamp to find abandoned credentials.
• Rotate tokens after personnel, environment or ownership changes.
• Delete a token immediately if its secret is exposed.

Frequently asked questions

What does a Webhook Relay access token control?

An access token has two independent controls. Its permission role limits REST, MCP and account-agent actions, while bucket and tunnel scopes limit which event streams a connected agent may subscribe to. A scope does not grant or deny permission to edit that resource through the API.

Does an empty bucket or tunnel scope deny access?

No. An empty bucket or tunnel scope means all subscriptions are allowed for backward compatibility. Use the reserved !none value to disable that subscription type. If !none appears with another pattern, !none wins and no subscriptions of that type are allowed.

What happens to access tokens created before permissions were added?

Legacy tokens without a permission role keep their existing unrestricted API behavior. They appear as Legacy full access in the dashboard and remain unchanged until an operator explicitly selects a role. Existing user sessions are not affected.

Can an Admin access token create or rotate other tokens?

No. Standalone access tokens cannot create, update or delete access tokens, even when assigned the Admin role. They also cannot be exchanged for a browser session or become a Webhook Relay platform administrator.

How quickly does token revocation take effect?

A token change is invalidated immediately on the server that processes it. Allow up to five minutes for another server or an already connected relay agent to revalidate the credential and disconnect after revocation or a subscription-scope change.

Can a token have more access than the organization member who created it?

No. A member can assign only token roles allowed by that member's own role. In an organization, the current member role and token role are both enforced, so the more restrictive result wins. Removing the member also invalidates organization-bound tokens created by that member.

Related documentation

• Install and authenticate the relay CLI
• Receive webhooks on localhost
• Connect through MCP
• Organization member roles
• Security and technology overview