Skip to content

API Tokens

ServiceHop uses API tokens for authentication. Tokens provide secure, scoped access to the platform.

Token Format

Tokens use the shp_ prefix followed by a random string:

shp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Tokens are stored as SHA-256 hashes in the database. The full token value is only shown once at creation time.

Creating Tokens

Tokens are created through the web UI:

  1. Navigate to Administration > API Tokens
  2. Click Create Token
  3. Enter a name and optional description
  4. Select a role (MASTER, USER, or VIEWER)
  5. Optionally set an expiration date
  6. Click Create

The full token is displayed once. Copy and store it securely.

Token Properties

Property Description
Name Human-readable identifier
Role Permission level (MASTER, USER, VIEWER)
Expiration Optional date when token becomes invalid
Status Active or Revoked

Token Lifecycle

Expiration

Tokens can have an optional expiration date:

Setting Behavior
No expiration Token valid indefinitely
With expiration Token automatically invalid after date

Revocation

Revoked tokens are immediately invalid. Revocation is reversible through reactivation.

To revoke a token:

  1. Navigate to Administration > API Tokens
  2. Find the token
  3. Click Revoke

Reactivation

Revoked tokens can be reactivated if needed:

  1. Navigate to Administration > API Tokens
  2. Find the revoked token
  3. Click Activate

Deletion

Permanently deleting a token is irreversible. Delete tokens that are no longer needed.

Security Best Practices

Secure Storage

  • Store tokens in environment variables or a secrets manager
  • Never commit tokens to source control
  • Protect configuration files with appropriate permissions
chmod 600 ~/.servicehop/config

Token Rotation

Rotate tokens periodically:

  1. Create a new token
  2. Update CLI configuration
  3. Revoke the old token

Minimal Permissions

Use the least privileged role for each use case:

Use Case Recommended Role
CI/CD data ingestion USER
Monitoring dashboards VIEWER
Administration scripts MASTER

CLI Configuration

The CLI uses tokens via environment variable or configuration file:

Environment Variable

export SERVICEHOP_API_TOKEN="shp_your_token_here"

Configuration File

Location: ~/.servicehop/config

api.url=https://servicehop.example.com
api.token=shp_your_token_here

Checking Token Information

Use the CLI whoami command to verify your token:

servicehop-cli whoami

Output: 

Token Information
─────────────────
ID:       tok_abc123
Name:     CLI Token
Role:     USER
Created:  2024-01-01T00:00:00Z
Expires:  2024-12-31T23:59:59Z