Issue and revoke tokens

Personal access tokens authenticate the watcher and other API clients. Creating and revoking tokens requires the workspace admin role. Members can view the audit list at Settings → Access Tokens but cannot mint or delete tokens. Roles and scopes: Security and permissions.

Create a token

In the web app

1. Sign in as an admin.
2. Go to Settings → Access Tokens.
3. Click Create token.
4. Enter a Name that identifies the client (for example, FPLC watcher, Lab 201).
5. Set User to whoever the token acts as. Data Hub attributes write actions, such as claiming a run, to this user. Defaults to you.
6. Pick an Expiration: 30 days, 90 days (the default), 1 year, or no expiry.
7. Under Scopes, click a preset, or click Customize scopes to pick individual scopes.
8. Click Create token.

The plaintext token is shown once: copy it immediately. It starts with dhub_ followed by a 64-character hex string.

Scope presets

A preset selects the minimum scopes a common client needs:

• Read-only: view instruments, runs, files, and watchers; change nothing
• MCP: what an MCP client does, including browse, download, claim, comment, reprocess, and delete runs
• Watcher: what a watcher needs to register, report runs, and upload files
• Lambda: what the processing Lambda needs to write run and file results

You cannot change a token's scopes after creation. To change them, revoke the token and create a new one.

Via the API

Token create/delete are admin-only and session-only (cookie auth). Bearer tokens cannot manage other tokens.

curl -X POST https://datahub.example.com/api/v1/tokens \
  -H "Cookie: session_cookie_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FPLC watcher",
    "scopes": ["instruments:read", "watchers:report", "runs:create", "runs:upload", "files:update"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

scopes is required and must be a non-empty list of explicit scopes; the wildcard * is rejected. expires_at is optional; if omitted, the token never expires. The response includes the plaintext once in the token field.

Use a token

With the watcher

During data-hub-watcher init, paste the token when prompted. Or set it first:

export DATA_HUB_API_KEY=dhub_your_token_here
data-hub-watcher init

With an MCP client

{
  "mcpServers": {
    "data-hub": {
      "url": "https://datahub.example.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer dhub_your_token_here"
      }
    }
  }
}

See MCP overview for the endpoint. Catalogs for tools, prompts, and resources are stubs until generated docs ship.

With the REST API

curl https://datahub.example.com/api/v1/instruments \
  -H "Authorization: Bearer dhub_your_token_here"

More in the API overview.

View tokens

Settings → Access Tokens shows name, prefix only (full token is never stored), last used, expiration, and created time.

Revoke a token

1. Go to Settings → Access Tokens.
2. Delete the token and confirm.

The token is invalidated immediately. Clients using it start receiving 401 Unauthorized.

curl -X DELETE https://datahub.example.com/api/v1/tokens/<token_id> \
  -H "Cookie: session_cookie_here"

After revoking a token

If a running watcher used that token:

1. Create a new token.
2. On the instrument PC, re-run data-hub-watcher init and enter the new token.
3. Restart the watcher (data-hub-watcher watch or the Windows service).

Token hygiene

• Name tokens so you can tell which PC or client each belongs to
• Set expirations for temporary setups
• Scope to least privilege; see Token scopes
• Revoke immediately when a watcher is decommissioned or a token may have been exposed

Tokens are hashed with SHA-256 before storage; plaintext is never persisted.