Credentials
Credentials store the connection details your tasks use to reach third-party systems such as Jira, Slack or AWS. Create, test and share them, and attach them to projects. The integration catalog lists the vendors Jaah connects to, starts a vendor's one-click Connect and takes votes for vendors; the NodeVault endpoints set up, rotate and migrate the key that seals credentials only your organization's nodes can open.
List credentials
Lists one page of the credentials the caller can see, newest first, with a `total` for paging by `page` and `per`. Filters by `type`, name search `q`, `mine`, `created_by_id`, `org_id` and whether secrets are stored (`secrets`). Never returns secret values.
Create credential
Creates a credential from a type, name, description and config; secret fields may arrive sealed with the seal key, which then requires a client-chosen `id` (409 when that id was ever used). The credential is personal unless `ownership` makes it the organization's, which requires the Org Owner or Org Admin role. Returns 201 with the credential, without secret values.
Bulk delete credentials
Deletes up to 10,000 credentials in one all-or-nothing change: either `ids` or `match` (the roster's filters), with `expect_count` the count you confirmed. Each is retired and audited as a single delete is, and the count deleted is returned.
Bulk move credentials
Files up to 10,000 credentials under the folder `to`, each keeping its own last name segment, in one all-or-nothing change: either `ids` or `match`, with `expect_count`. A name collision refuses the whole set, naming it. Returns the count moved.
Start credential connect
Starts the OAuth2 Connect flow for a saved credential and returns the provider's consent URL. Returns 400 until the credential stores its client ID, secret and the provider endpoints its type needs; in tenant organizations a type whose endpoints the credential supplies itself returns 403. Requires edit access to the credential.
Get NodeVault state
Returns the caller's organization's NodeVault state (`not_setup`, `active`, `frozen` or `not_in_plan`), its current key hash, and for each credential type whether it may be NodeVault and, if not, why.
List credential owners
Lists the owners of the credentials the caller can see, each with a credential count: with no parameters every owner, highest count first; with `q`, `ids` or `limit`: a search, names starting with `q` first, then by name, each count capped at 10,000 (`count_capped`). Each `id` is a value for the list's `owner_id` filter.
Get credential seal key
Returns the public key (base64 SPKI DER), algorithm and key id that seal secret field values in the client before they are sent. Returns 503 when the key is unavailable.
Test credential
Tests a connection from a `type` and `config`, filling blank secrets from the saved credential named by `id`. A completed test returns 200 with its outcome, whether it passed or failed; a NodeVault credential is never tested and returns `unsupported`. Not available in tenant organizations (403).
Browse credential tree
Lists one level of the credentials tree under the list's filters: the organizations holding credentials (operators only; 422 for anyone else), one organization's homes (shared, system, project, personal), or one folder's subfolders and the credentials directly in it. Each node carries a count of the credentials beneath it, capped at 1000 with `count_capped`. Never returns secret values.
List credential types
Lists the credential types in display order, each with its fields, whether it can be tested and which OAuth flows it offers. Forms render their fields from this list.
Delete credential
Deletes a credential and retires its id so it is never reused. Requires delete access to the credential. Returns 204 with no body.
Get credential
Returns one credential the caller can see, with its non-secret config, the names of its stored secrets in `secrets_set` and whether the caller may edit it. Never returns secret values.
Update credential
Updates a credential's name, description, type or config; omitted fields and config keys keep their stored values, so secrets need not be resent unless `type` changes, which starts the config empty. Sending `id` or `ownership`, or changing the destination URL while keeping a stored secret, returns 400. Requires edit access to the credential; returns the credential.
Get credential access
Returns who may use a credential: its owner when personal, whether it is a system credential, and the projects it is attached to that the caller can see. Never includes config.
List credential MCP links
Lists the projects that have linked an MCP connection, so their agent sessions reach its server. Requires view access to the connection; a project the caller cannot see is left out.
Get NodeVault eligibility
Returns whether a credential may be NodeVault: its type allows it and nothing on Jaah's servers uses it. `consumers` names each server-side use that blocks it.
Change credential owner
Moves a credential to personal, organization or system and, for personal, to a member of the org; a personal or system credential leaves its project home, and a system one leaves every project. Requires the Org Owner or Org Admin role; returns the credential.
List integrations
Lists the integration catalog: every vendor this edition offers, with its category, how it connects (OAuth, key or MCP), whether Jaah's OAuth app is set up (`oauth.state` is `app_not_configured` until it is) and its reader docs link. `connected` counts the caller's visible connections of the vendor's type and names the worst of their states (`needs_reconnect`, `test_failed`, `untested`, `ok`).
Get integration logo
Returns a catalog vendor's logo as `image/svg+xml`, cached as immutable. Returns 404 for a vendor with no logo.
Start integration connect
Starts a one-click OAuth Connect for a catalog vendor or a forge without saving a credential first, and returns the consent URL; the credential is created when the vendor redirects back. The body names it (`name`, optional for a forge), who it belongs to (`owner`), the projects to attach it to and optionally your own OAuth app; a forge (`github`, `gitlab`, `bitbucket`, `azure_devops`) is always your own personal connection on Jaah's app, landing on `return_to` with GitHub's app picked by `app`. Returns 409 (GitHub: 503) while Jaah's app is not set up and no client was given, and 404 for a vendor without OAuth.
Withdraw integration vote
Withdraws your vote for a catalog vendor. Withdrawing a vote you never cast is not an error. Returns 404 for a vendor without OAuth.
Vote for integration
Votes for a catalog vendor whose one-click Connect is not ready yet (`oauth.state` is `app_not_configured`). Each person has one vote per vendor, across every organization they belong to, so voting again changes nothing; `voted` on the gallery card reflects it. Returns 409 for a caller with no person behind it, such as a machine user, and once the vendor is ready to connect, and 404 for a vendor without OAuth.
Get NodeVault
Returns the organization's NodeVault status: plan flags, current and previous key hashes with their credential counts, each node's identity fingerprint and per-key delivery state, and the running operation, never key material. Returns 403 when NodeVault is neither in the plan nor set up. Requires the Org Owner or Org Admin role.
List NodeVault credentials
Lists the organization's credentials that are or can be NodeVault (`eligible`, with `state` `kms` or `nodevault`) and those that cannot, each with the reason. Requires the Org Owner or Org Admin role.
Retry grant
Retries a failed delivery or removal of a NodeVault key on a node; returns 202 with the delivery's new state. Returns 409 when it has not failed. Requires the Org Owner or Org Admin role.
Retire NodeVault key
Retires an old NodeVault key, removing it from every node (an offline node when it reconnects), and returns 202 with the operation id; it cannot be undone once complete. Returns 409 while credentials still use the key (naming how many), when the key is not an old one, or while another NodeVault operation runs. Requires the Org Owner or Org Admin role and a plan that includes NodeVault.
Start NodeVault migration
Moves `credential_ids`, `all` eligible credentials, or none (`skip`) to NodeVault, recording the choice on a setup that waits for it or else starting a migration to the current key; returns 202 with the operation id. `skip` is accepted only while setup waits, and is the one choice allowed when the plan no longer includes NodeVault. Returns 409 while another NodeVault operation runs, and requires the Org Owner or Org Admin role.
Reset node identity
Forgets a node's NodeVault identity key and its key deliveries, so the node can register a new identity and receive the keys again. Recorded in the audit log. Requires the Org Owner or Org Admin role.
Get NodeVault operation
Returns one NodeVault operation with its step, counts (credentials migrated, skipped and failed, and how many nodes hold its key) and each credential's result with its reason. Requires the Org Owner or Org Admin role.
Abandon NodeVault operation
Abandons a running NodeVault operation and returns 202: a setup or rotation before its new key is in use (that key is then removed from every node), a migration or a rotation's migration and rekey at any step (credentials already moved stay moved), or a key retirement while some node still holds the key (the key goes back to every node). Returns 409 when the operation has finished or can no longer be abandoned. Requires the Org Owner or Org Admin role.
Retry migration item
Retries moving one credential that failed to move to NodeVault; returns 202. Returns 409 when it has not failed or while another NodeVault operation runs, and 403 when the plan does not include NodeVault. Requires the Org Owner or Org Admin role.
Start NodeVault rotation
Starts a NodeVault rotation with a new public key, its confirmed backup, and the new private key wrapped under the current NodeVault key (`chain_blob`); returns 202 with the operation id, and nodes keep the old key until it is retired. Returns 422 when `chain_blob` is not wrapped under the current key, and 409 when NodeVault is not set up, no node holding the current key is online, or another NodeVault operation runs (with its `operation_id`). Requires the Org Owner or Org Admin role and a plan that includes NodeVault.
Get NodeVault seal key
Returns the organization's current NodeVault public key (base64 SPKI DER), algorithm and key id, to seal a NodeVault credential's secret fields in the client. Returns 403 when the plan does not include NodeVault and 409 when NodeVault is not set up.
Start NodeVault setup
Starts NodeVault setup with a new public key, its confirmed backup, and the key wrapped to each capable node; returns 202 with the operation id. Returns 422 with `missing` and `extra` node ids when the wrapped keys do not cover exactly the capable nodes, and 409 when no capable node is online, NodeVault is already set up, or another NodeVault operation runs (with its `operation_id`). Requires the Org Owner or Org Admin role and a plan that includes NodeVault.
Start NodeVault setup over
Retires a current NodeVault key that no node holds, with its grants, so Setup can run again with a fresh key; credentials sealed under it can no longer be opened and must be re-entered. Returns 409 while any node has the key delivered, when NodeVault is not set up, or while another NodeVault operation runs. Requires the Org Owner role.
Attach project credential
Attaches a credential to a project so work in that project can use it. Requires edit access to the project; the credential's owner may attach it, and an Org Owner or Org Admin may attach any organization credential but not someone else's personal one. A system credential or an agent account's own key returns 422; otherwise returns 201 when attached and 200 when already attached.
Detach project credential
Detaches a credential from a project. Requires edit access to the project, plus ownership of the credential or the Org Owner or Org Admin role. Returns 404 when it is not attached there, 204 with no body otherwise.