Managing tokens

Create, use, and revoke personal access tokens that authenticate the watcher and other clients with the Data Hub REST API.

ForAdministrators and members

Personal access tokens authenticate the watcher and other API clients with the Data Hub API. This guide covers creating, using, and revoking tokens. For the bigger picture on roles and scopes, see Security & permissions.

Creating and revoking tokens requires the workspace admin role. Regular members can view the workspace token audit list at Settings > Access Tokens but cannot mint or delete tokens. Ask an existing admin if you need a token issued.

Creating a token

In the web app

Sign in to the Data Hub web app as an admin.
Go to Settings > Access Tokens.
Click Create Token.
Enter a descriptive name (e.g., “FPLC watcher – Lab 201”).
Optionally set an expiration date.
Click Create.

The plaintext token is displayed once: copy it immediately. It cannot be retrieved again. The token starts with dhub_ followed by a 64-character hex string.

Via the API

curl -X POST https://datahub.example.com/api/v1/tokens \
  -H "Cookie: <session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{"name": "FPLC watcher", "expires_at": "2027-01-01T00:00:00Z"}'

The expires_at field is optional. If omitted, the token never expires. The response includes the plaintext token in the token field; this is the only time it's returned.

Using a token

With the watcher

During data-hub-watcher init, paste the token when prompted for the API key. Alternatively, set it as an environment variable:

export DATA_HUB_API_KEY=dhub_your_token_here
data-hub-watcher init

The watcher stores the API key in its environment configuration and uses it for all subsequent API calls.

With an MCP client

Data Hub exposes a Model Context Protocol (MCP) server so AI assistants can query your data. Add it to your MCP client configuration, for example in Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):

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

See the MCP server reference for the full tool, resource, and prompt catalog, plus client-specific installation steps.

With the API directly

Pass the token in the Authorization header:

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

Viewing tokens

Go to Settings > Access Tokens in the web app. The table shows:

Column	Description
Name	The label you gave the token
Token	The prefix only (e.g., `dhub_a1b2…`): the full token is never stored
Last used	When the token was last used to authenticate an API request
Expires	Expiration date, or "Never"
Created	When the token was created

Revoking a token

In the web app

Go to Settings > Access Tokens.
Click the delete button next to the token you want to revoke.
Confirm the deletion.

The token is immediately invalidated. Any watcher or client using it will start receiving 401 Unauthorized errors.

Via the API

curl -X DELETE https://datahub.example.com/api/v1/tokens/<token-id> \
  -H "Cookie: <session-cookie>"

Security notes

Tokens are hashed with SHA-256 before storage. The plaintext is never persisted.
Token create and delete are admin-only operations. Admins can revoke any user's token to support off-boarding and incident response.
Use descriptive names so you can identify which watcher or client each token belongs to.
Set expiration dates for tokens used in temporary setups.
Revoke tokens immediately when a watcher is decommissioned or a token may have been exposed.

After revoking a token

If you revoke a token that a running watcher is using, the watcher will start failing on its next heartbeat or API call. To fix it:

Create a new token.
On the instrument PC, re-run the setup wizard:
```
data-hub-watcher init
```
Enter the new token when prompted.
Restart the watcher:
```
data-hub-watcher watch
```

On this page