API Reference

Complete REST API documentation for TokenPass Server

TokenPass Server exposes a REST API on http://localhost:21000. All endpoints are prefixed with /api/ and accept/return JSON.

TokenPass uses a two-step authentication: first unlock the wallet with /api/login, then get access tokens with /api/auth.

Quick Start

Register a Wallet (First Time Only)

curl -X POST http://localhost:21000/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "password": "my-secure-password",
    "displayName": "Alice"
  }'

curl -X POST http://localhost:21000/api/login \
  -H "Content-Type: application/json" \
  -d '{"password": "my-secure-password"}'

Get an Access Token

curl -X POST http://localhost:21000/api/auth \
  -H "Content-Type: application/json" \
  -d '{
    "password": "my-secure-password",
    "host": "example.com",
    "expire": "1h",
    "scopes": "sign,encrypt"
  }'

Use the Token

curl -X POST http://localhost:21000/api/sign \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_ACCESS_TOKEN" \
  -d '{"message": "Hello World"}'

Endpoints

Wallet Management

Access Tokens

Generate OAuth-style tokens for hosts

Cryptographic Operations

Sign and encrypt messages

Identity Management

Read and update BAP profile

Wallet Management

POST /api/register

Create a new wallet with an encrypted master seed. Only call this once during initial setup.

{
  "password": "string (required)",
  "displayName": "string (optional)",
  "paymail": "string (optional)",
  "logo": "string (optional, URL or data URI)"
}

Field	Type	Description
`password`	string	Password to encrypt the master seed
`displayName`	string	Your display name
`paymail`	string	Your paymail address
`logo`	string	Profile image URL or data URI

{
  "success": true
}

POST /api/login

Unlock the wallet by decrypting the master seed.

{
  "password": "string (required)"
}

{
  "success": true
}

Must be called after server restart or /api/logout before using protected endpoints.

POST /api/logout

Lock the wallet by clearing the in-memory decrypted seed.

{
  "success": true
}

GET /api/status

Check the current wallet status.

{
  "seed": true,
  "unlocked": true,
  "keys": [...],
  "states": [...]
}

Field	Type	Description
`seed`	boolean	`true` if wallet exists
`unlocked`	boolean	`true` if wallet is unlocked
`keys`	array	Derived keys (empty if locked)
`states`	array	Access token states (empty if locked)

POST /api/export

Export the master seed and mnemonic phrase.

Never share your seed or mnemonic. Anyone with access has full control of your identity.

{
  "password": "string (required)"
}

{
  "seed": "hex-encoded-seed",
  "mnemonic": "twelve or twenty-four word phrase"
}

Access Tokens

POST /api/auth

Generate an OAuth-style access token for a specific web host.

{
  "password": "string (required)",
  "host": "string (required)",
  "expire": "string (optional, default: 'once')",
  "scopes": "string (optional, comma-separated)",
  "icon": "string (optional)"
}

Expire Options:

Value	Duration
`once`	10 seconds (default)
`1h`	1 hour
`1d`	1 day
`1w`	1 week
`1m`	1 month
`forever`	No expiration

Scope Options:

Scope	Description
`sign`	Sign messages
`encrypt`	Encrypt messages
`decrypt`	Decrypt messages
`read_profile`	Read BAP identity
`write_profile`	Modify BAP identity
`read_state`	Read per-host state
`write_state`	Write per-host state
`fund`	Request funding/payment
`transfer`	Transfer tokens/assets

{
  "success": true,
  "accessToken": "uuid-v4-token",
  "expireTime": 1234567890123,
  "host": "example.com"
}

Cryptographic Operations

POST /api/sign

Sign a message with the derived Bitcoin private key for the authenticated host.

Requires Authorization: ACCESS_TOKEN header (no "Bearer" prefix)

{
  "message": "string (required)",
  "encoding": "string (optional, default: 'utf8')"
}

Field	Type	Description
`message`	string	The message to sign
`encoding`	string	`utf8`, `hex`, or `base64`

{
  "address": "1BitcoinAddress...",
  "sig": "signature-string",
  "message": "original-message",
  "ts": 1234567890123
}

POST /api/encrypt

Encrypt a message using ECIES.

Requires Authorization: ACCESS_TOKEN header with encrypt scope

{
  "message": "string (required)"
}

{
  "encrypted": "encrypted-message-data"
}

Identity Management

GET /api/profile

Retrieve the global BAP identity profile. No authentication required.

{
  "host": "global",
  "displayName": "Alice",
  "paymail": "alice@example.com",
  "logo": "https://...",
  "bapID": "identity-key-string"
}

POST /api/profile

Update the global BAP identity profile.

{
  "displayName": "string (optional)",
  "paymail": "string (optional)",
  "logo": "string (optional)",
  "customField": "any value"
}

{
  "success": true
}

Error Handling

All errors return a consistent format:

{
  "error": "Error message description",
  "code": 1,
  "success": false
}

Code	Description
`1`	Wallet is locked
`2`	Missing authorization header
`3`	Invalid access token
`5`	Access token has expired

HTTP Status	Description
`200`	Success
`400`	Bad Request - missing required fields
`401`	Unauthorized - invalid password or token
`417`	Expectation Failed - wallet not created
`500`	Internal Server Error

Configuration

CORS

Configure allowed origins:

TOKENPASS_ORIGIN_WHITELIST=https://app1.com,https://app2.com bun dev

Storage

All data is stored in ~/.tokenpass/:

File	Description
`seed.db`	Encrypted master seed (AES-256-CBC)
`keys.db`	Derived Bitcoin keys per host
`state.db`	Access tokens and per-host state

API Reference

Wallet Management

Access Tokens

Cryptographic Operations

Identity Management

On this page