# ohapi

> ohapi stores application secrets (API keys, database URLs, tokens) per project and environment. The application encrypts each value with AES-256-GCM before it reaches the database. A CLI loads secrets into a process, and a REST API manages projects, environments and secrets.

Pricing: https://ohapi.dev/pricing — plans, limits and the contact address.

For AI agents and automation, use the structured surfaces below. Do not scrape the HTML pages.

## Rules for agents that handle secrets

- Do not print, log or repeat a secret value. Do not write a secret value into a chat, a commit or an issue.
- To give secrets to a command, use `ohapi run -- <command>`. The CLI injects the values into the child process and writes nothing to disk. `ohapi pull` writes real values to `.env.local`; use it only when a person asks for that file.
- To check a secret, read its metadata, not its value. `GET /api/v1/projects/{projectId}/environments/{environment}/secrets/{key}` returns the version, type, format and dates. It returns no value and writes no audit row.
- Read a value only when the task needs it. `GET …/secrets/{key}/value` returns the value and writes a `READ` row to the project's audit log.
- A write can return `202` instead of `200`. `202` means that the change waits for approval by a second admin (dual control). The change is not applied yet. Follow the `Location` header to `GET /api/v1/change-requests/{id}` to see its status. An API key cannot approve a change.
- A write to an environment named `production` requires the header `x-confirm-production: true`. Send it only when a person confirms the production change.
- `404` means "does not exist" or "you have no access". The API does not tell the two apart.

## CLI

- Install: the command is `ohapi` (Node 20 or later). The npm registry has `ohapi-cli` 0.0.1 only. That version has no `ohapi mcp` and no `ohapi login --device`. These need `ohapi-cli` 0.2.0 or later. Until that version is published, install from the ohapi repository (`cd cli && npm install && npm link`). When version 0.2.0 is on npm, `npm install -g ohapi-cli` installs it. Do not run that command before then: it replaces the linked version with 0.0.1.
- [CLI guide](https://ohapi.dev/docs): log in, select a project, pull, run
- In CI, do not run `ohapi login`. Set `OHAPI_TOKEN`, `OHAPI_PROJECT_ID` and `OHAPI_ENVIRONMENT`.

## API

- [OpenAPI document (YAML)](https://ohapi.dev/openapi.yaml): every endpoint, request and response. Public, no API key required.
- Model Context Protocol: `POST /api/v1/mcp` (Streamable HTTP, bearer key, stateless). The CLI command `ohapi mcp` is a stdio bridge to it and needs `ohapi-cli` 0.2.0 or later.
- Authentication: `Authorization: Bearer <API key>`. A key has the same access as the user or service account that owns it.
- GitHub Actions without a stored key: create an OIDC trust in the dashboard, then send the workflow's OIDC token to `POST /api/v1/oidc/github`. The response is an API key that expires after one hour. The server accepts each token once.
- Kubernetes: the External Secrets Operator generic Webhook provider can read an environment (`GET /api/v1/secrets`) or one secret value (`GET …/secrets/{key}/value`). Use a service-account key with the `VIEWER` role. Each successful refresh writes one `READ` audit row: one row for an environment, one row for each key for a value. Example manifests are in the `k8s/external-secrets/` directory of the ohapi repository, which is private.

## Agents and CI

- MCP server: `ohapi mcp` (`ohapi-cli` 0.2.0 or later) starts a Model Context Protocol server over stdin/stdout for Claude Code, Cursor and other agents. It lists projects, environments and secret metadata and can propose changes. It does not return secret values unless a person starts it with `--allow values`, and it cannot approve a change.
- GitHub Actions: from repositories in the Obsidian-Heron organization, `uses: Obsidian-Heron/ohapi/action@<ref>` loads an environment into `GITHUB_ENV` and masks every value. It uses the workflow's OIDC token. No stored key is needed.
- GitHub Actions secrets sync: an admin can instead push an environment into GitHub Actions secrets ahead of time, from the project's Sync tab. Pull at run time with the action, or push ahead of time with the sync.
- Terraform: the provider `obsidian-heron/ohapi` on the Terraform Registry manages projects, environments and secrets. A secret's Read is a metadata read and writes no audit row. The data source `ohapi_secret_value` reads a value and writes one `READ` audit row.
- Node SDK: the `sdk/` directory holds `ohapi-sdk`, a typed client for secrets, projects, environments and change requests. A write returns `pending: true` when dual control holds it. It is not published to npm yet.
- Python SDK: `pip install ohapi` (Python 3.10 or later, no dependencies). Same calls as the Node SDK; a held write returns `Pending`.
- Go SDK: `go get github.com/Obsidian-Heron/ohapi-go@v0.1.0` (Go 1.27 or later, `net/http` only). Same calls as the Node SDK.

## Trust and security

- Notifications (email, Slack-compatible webhook, signed event webhook) are configured per project in the dashboard. They name keys and never carry values. There is no API for them.
- An admin can stream the audit log to a signed webhook (while the sink is enabled, at least one time per event for rows up to 7 days old; receivers deduplicate on the event id).
- [Security](https://ohapi.dev/security): encryption, key rotation, audit log, access control
- [Privacy Policy](https://ohapi.dev/privacy)
- [Terms of Service](https://ohapi.dev/terms)
- [security.txt](https://ohapi.dev/.well-known/security.txt): how to report a vulnerability