OSL

Open Secrets Language

Open Secrets Language (OSL)

A capability-driven abstraction API for secrets, leases, rotation, and sync workflows across heterogeneous providers. Build one client. Run it against Vault-class backends, cloud secret managers, and operator-driven sync systems without guessing what’s supported.

Read the OSL API Specification View API

OSL v1.0.0 Snapshot

  • • Provider-agnostic API surface for KV secrets + taint lifecycle across heterogeneous backends
  • • Capability discovery is mandatory via GET /osl/v1/capabilities/get (clients adapt safely at runtime)
  • • Required core endpoints for put|get|delete|destroy|list|describe + taint|untaint|is-tainted
  • • Capability-gated optional modules: kv.versioning, lease.issue, rotation.policy / rotation.rotate, sync.manage

Feature pillars

Unified KV Secret Lifecycle (Required Core)

Use one API to create, update, read, delete, destroy, list, and describe secrets independent of the underlying provider.

Mandatory Capability Discovery (No Guessing)

Every client starts by calling GET /osl/v1/get-capabilities, then enables features only when the server and selected backend advertise them.

Optional Modules for Real Workflows

Extend beyond static KV with capability-gated modules: Versioning, Dynamic credentials, Rotation, Sync/materialization

Why OSL

OSL exists because secrets providers don’t share a single feature set. Some support versioning, some support dynamic credentials, others specialize in Kubernetes materialization or rotation. Developers want a single standard with a simple API. Security teams want a single integration surface that enables consolidation.

OSL solves this with:

  1. A small required core that every OSL v1 server must implement
  2. Optional modules that are only used when capability discovery says they’re available
  3. A consistent interface: URL-major versioning (/osl/v1/...), snake_case fields, and a standard error envelope

Built to reduce complexity

OSL v1.0.0 is designed to map cleanly onto systems including:

  • HashiCorp Vault, OpenBao, HCP Vault
  • AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager
  • CyberArk Conjur, Doppler, Delinea Secret Server
  • Kubernetes External Secrets Operator (ESO)

Exact capabilities vary by backend; clients should rely on get-capabilities.

How it works

  1. Authenticate consistently
  • All requests use bearer auth
  • Clients MUST send a bearer token on every request
  1. Discover capabilities at startup
  • Call GET /osl/v1/get-capabilities once, cache it, and drive client behavior from that result
  1. Use the required core, then opt into modules
  • Always available: KV lifecycle + taint endpoints
  • Only when advertised: versioning, leases, rotation, sync

Required core endpoints

These endpoints MUST be implemented by an OSL v1 server:

  • POST /osl/v1/put-secret
  • POST /osl/v1/get-secret
  • POST /osl/v1/delete-secret
  • POST /osl/v1/destroy-secret
  • POST /osl/v1/list-secrets
  • POST /osl/v1/describe-secret
  • POST /osl/v1/taint-secret
  • POST /osl/v1/untaint-secret
  • POST /osl/v1/is-secret-tainted

Optional capability modules

  • Versioning (when backend has kv.versioning)
    • POST /osl/v1/list-secret-versions
    • POST /osl/v1/get-secret-version
  • Dynamic credentials / leases (when backend has lease.issue)
    • POST /osl/v1/issue-credential
    • POST /osl/v1/renew-credential
    • POST /osl/v1/revoke-credential
  • Rotation (when backend has rotation.policy and/or rotation.rotate)
    • POST /osl/v1/put-rotation-policy
    • POST /osl/v1/rotate-secret
  • Sync / materialization (when backend or server has sync.manage)
    • POST /osl/v1/put-sync
    • POST /osl/v1/run-sync
    • POST /osl/v1/get-sync-status
    • POST /osl/v1/list-syncs
    • POST /osl/v1/delete-sync

Reliability & error handling

OSL standardizes responses so clients can be strict and predictable:

  • Recommended success envelope: includes osl-version and result
  • Required error envelope for any non-2xx response, with structured error codes
  • Optional module calls against unsupported backends should return a structured feature-not-supported error

Management API

For inventory-style workflows, OSL also includes:

  • GET /osl/v1/list-apps
  • GET /osl/v1/list-backends

Start using OSL v1

Read the OSL API Specification View API

Stay in the loop

Get OSL updates, implementation guides, and release notes.

By subscribing, you agree to our Privacy Policy.

Frontend-only Listmonk form. Update params.newsletter in hugo.toml to match your existing Listmonk installation.