OmniToken

Token management SDK that bridges goauth credentials with vault-based storage via omnivault.

Overview

OmniToken enables applications (particularly MCP servers) to:

• Store and retrieve goauth Credentials in various vault backends
• Automatically manage OAuth2 token lifecycle (acquisition, refresh, caching)
• Implement goauth's TokenSet interface for vault-backed token storage
• Support multiple credential types (OAuth2, JWT, Basic Auth, API keys, GCP service accounts)

Architecture

┌──────────────────────────────────────────────────────────────┐
│ Applications │
│ ┌───────────┐ ┌───────────┐ ┌─────────────────┐ │
│ │ mcp-google│ │ mcp-aha │ │ mcp-confluence │ │
│ └─────┬─────┘ └─────┬─────┘ └────────┬────────┘ │
│ └──────────────┼─────────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ omnitoken │ ← Credential & token mgmt │
│ └────────┬────────┘ │
└───────────────────────┼──────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌────▼────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ goauth │ │ omnivault │ │ oauth2 │
│(creds) │ │ (storage) │ │ (tokens) │
└─────────┘ └─────┬─────┘ └───────────┘
│
┌───────────────┼───────────────┐
│ │ │
┌────▼────┐ ┌─────▼─────┐ ┌─────▼─────┐
│1Password│ │ Bitwarden │ │ Keeper │
└─────────┘ └───────────┘ └───────────┘

Installation

go get github.com/plexusone/omnitoken

Quick Start

From Vault URI

import"github.com/plexusone/omnitoken"// Create from vault URI (1Password, Bitwarden, file, etc.)mgr, err:=omnitoken.NewFromVaultURI("op://MyVault")
iferr!=nil {
log.Fatal(err)
}
defermgr.Close()
// Get credentials stored in the vaultcreds, err:=mgr.GetCredentials(ctx, "my-api")
// Get an authenticated HTTP clientclient, err:=mgr.GetClient(ctx, "my-api")

From Credentials File

// Load from goauth CredentialsSet filemgr, err:=omnitoken.NewFromCredentialsFile("/path/to/credentials.json")
iferr!=nil {
log.Fatal(err)
}
defermgr.Close()
// Get client for a specific accountclient, err:=mgr.GetClient(ctx, "myaccount")

Auto-Detection

// Auto-detect from environment variables:// - OMNITOKEN_VAULT_URI: vault URI// - OMNITOKEN_CREDENTIALS_FILE: credentials file pathmgr, err:=omnitoken.NewAuto()
iferr!=nil {
log.Fatal(err)
}
defermgr.Close()

Credential Sources

Source	Constructor	Description
Vault URI	NewFromVaultURI(uri)	Any omnivault-supported backend
Credentials File	NewFromCredentialsFile(path)	goauth CredentialsSet JSON
CredentialsSet	NewFromCredentialsSet(set)	In-memory from goauth.CredentialsSet
Single Credential	NewFromCredentials(name, creds)	Single goauth.Credentials
Environment	NewFromEnv(prefix)	Environment variables
Directory	NewFromDirectory(dir)	File-based storage
Auto	NewAuto()	Auto-detect from environment

Supported Vault URIs

Provider	URI Pattern	Requirements
1Password	op://vault	OP_SERVICE_ACCOUNT_TOKEN env var
Bitwarden	bw://org-id	BW_ACCESS_TOKEN, BW_ORGANIZATION_ID env vars
Keeper	keeper://	KSM_TOKEN or KSM_CONFIG env var
File	file:///path	None
Environment	env://PREFIX_	None
Memory	memory://	None (testing)

To use 1Password, Bitwarden, or Keeper, import omnivault-desktop:

import _ "github.com/plexusone/omnivault-desktop"

Environment Variables

Variable	Description
OMNITOKEN_VAULT_URI	Vault URI for NewAuto()
OMNITOKEN_CREDENTIALS_FILE	Credentials file path for NewAuto()
OMNITOKEN_CREDENTIALS_NAME	Default credential name (used by MCP servers)

API Reference

TokenManager

// Create token managermgr, err:=omnitoken.New(omnitoken.Config{
Vault: vault, // omnivault.Vault implementationAutoRefresh: true, // Auto-refresh expired tokensRefreshBuffer: 5*time.Minute, // Refresh before expiry
})
// Credential operationscreds, err:=mgr.GetCredentials(ctx, "name")
err:=mgr.SetCredentials(ctx, "name", creds)
err:=mgr.DeleteCredentials(ctx, "name")
names, err:=mgr.ListCredentials(ctx)
// Token operationsclient, err:=mgr.GetClient(ctx, "name") // Get authenticated HTTP clienttoken, err:=mgr.GetToken(ctx, "name") // Get OAuth2 tokentoken, err:=mgr.RefreshToken(ctx, "name") // Force refresh// goauth integrationtokenSet:=mgr.TokenSet() // Get goauth TokenSet interfacecredStore:=mgr.CredentialsStore() // Get credentials store// Cleanuperr:=mgr.Close()

Loading Specific Credential Types

// Load Google service accounterr:=mgr.LoadGoogleServiceAccount(ctx, "google", "/path/to/sa.json", []string{
"https://www.googleapis.com/auth/presentations.readonly",
"https://www.googleapis.com/auth/documents.readonly",
})
// Load from goauth CredentialsSet fileerr:=mgr.LoadGoauthCredentials(ctx, "myservice", "/path/to/creds.json", "accountKey")

Credential Types

OmniToken supports all goauth credential types:

Type	Description
oauth2	OAuth2 client credentials, authorization code, etc.
jwt	JWT bearer tokens
basic	HTTP Basic Auth
headerquery	Custom header/query authentication
gcpsa	Google Cloud service account

Token Lifecycle

The TokenManager handles the complete token lifecycle:

1. Retrieves credentials from vault
2. Checks for cached/stored valid token
3. Refreshes expired tokens using refresh_token if available
4. Obtains new tokens when refresh isn't possible
5. Stores tokens in vault for persistence across restarts

Usage in MCP Servers

OmniToken is designed for use in MCP servers. See mcp-google for a complete example:

import (
"github.com/plexusone/omnitoken"
_ "github.com/plexusone/omnivault-desktop"
)
funcmain() {
// Create token manager from vaultmgr, err:=omnitoken.NewFromVaultURI(os.Getenv("OMNITOKEN_VAULT_URI"))
iferr!=nil {
log.Fatal(err)
}
defermgr.Close()
// Get credentials for the servicecreds, err:=mgr.GetCredentials(ctx, os.Getenv("OMNITOKEN_CREDENTIALS_NAME"))
iferr!=nil {
log.Fatal(err)
}
// Create authenticated HTTP clientclient, err:=creds.NewClient(ctx)
iferr!=nil {
log.Fatal(err)
}
// Use client with service SDK...
}

License

MIT