OAuth Vault

oauth-vault is an OAuth token service for multi-tenant apps. It stores tokens encrypted in PostgreSQL, refreshes them, and returns valid access tokens through an API.

Quick Start

1) Setup

make install
make setup        # generates .env with secure random keys

2) Start with Docker Compose

docker compose up -d postgres oauth-vault
curl -fsS http://localhost:8090/health

Notes:

• Host Postgres port defaults to 55432 (OAUTH_VAULT_POSTGRES_HOST_PORT to override).
• OAUTH_VAULT_AUTO_CREATE_SCHEMA=false by default.
• Use SQL migrations for production deployments.
• If you reuse an old local Postgres volume and hit schema errors, reset local stack: make local-reset

3) Build the CLI client

make client-build
./dist/vaultctl version

Basic Usage

export OAUTH_VAULT_BASE_URL=http://localhost:8090
export OAUTH_VAULT_TOKEN=<your-api-key>  # from make setup output
export TENANT_REF=my-tenant

1. Create or update a provider:

PROVIDER_ID=$(./dist/vaultctl provider upsert-preset \
  --tenant-ref "$TENANT_REF" \
  --preset-slug github \
  --provider-slug github-main \
  --client-id "$GITHUB_CLIENT_ID" \
  --client-secret "$GITHUB_CLIENT_SECRET" \
  --output id)

2. Complete browser authorization:

./dist/vaultctl connection browser \
  --tenant-ref "$TENANT_REF" \
  --owner-ref user:miguel \
  --provider-id "$PROVIDER_ID" \
  --scopes "repo,user:email"

3. Resolve a valid token:

./dist/vaultctl token resolve \
  --tenant-ref "$TENANT_REF" \
  --owner-ref user:miguel \
  --provider-slug github-main \
  --output token

Security

See SECURITY.md for vulnerability reporting and production hardening.

Docs

• Provider setup commands (every preset): docs/provider-setup.md
• Docker deployment: docs/deploy-docker.md
• CLI reference: client/README.md
• API routes: docs/api-overview.md
• Architecture/refresh behavior: docs/architecture.md
• Auth model: docs/auth-model.md
• DB schema notes: docs/db-schema.md
• Testing: docs/testing.md
• Release/versioning: docs/release-workflow.md

License

Apache License 2.0. See LICENSE for details.