---
title: "Add an org member by wallet (owner-only, v1.77)"
method: POST
path: "/orgs/v1/{org_id}/members"
tags: ["Org"]
---

# Add an org member by wallet (owner-only, v1.77)

`POST /orgs/v1/{org_id}/members`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/orgs/v1/{org_id}/members`
- Auth: API key in header `SIGN-IN-WITH-X`

Owner-only. Adds a member by wallet address with a role. A brand-new wallet is provisioned as a `human` principal; an existing wallet is added by its resolved principal regardless of `type` (informational, not an authz gate). For non-member automation, prefer a per-project grant. Audited. vault-agent-envelopes: custody follows membership for `human` and `agent` principals alike — the member becomes a desired envelope recipient on every present and future vault the org owns (a `ci` principal does not), and the cap on custody-eligible memberships (MAX_EPOCH_ROTATION_ENVELOPES) is reserved at this add, keyed or not (422 MAX_EPOCH_ROTATION_ENVELOPES_EXCEEDED). vault-multi-writer rev 47: `next_actions` additionally carries a `sync_writers` entry naming the org's vaults where the new member is NOT yet an active, non-gateway-blocked writer — the signal to run `add_writer_key{"writer"}` (or `repos access sync`) for them; omitted when there is no such vault. No server-side writer admission ever happens on this route.

## Path parameters

- `org_id` string, uuid, required

## Headers

- `SIGN-IN-WITH-X` string, required

## Request body

- object
  - `wallet` string, required
  - `role` 'owner' | 'admin' | 'developer' | 'billing' | 'viewer'

## Response `201`

Member added

- object
  - `status` string
  - `principal_id` string, uuid
  - `role` string
  - `envelope` object: vault-agent-envelopes D6: the new member's vault-custody state. `enrolled_pending_wrap` — an active key; a key-holder's next vault operation wraps each vault to it. `not_enrolled` — the MEMBER's next vault operation enrolls its keystore key (nothing is asked of the owner). `not_applicable` — a `ci` principal.
    - `state` 'enrolled_pending_wrap' | 'not_enrolled' | 'not_applicable'
    - `ek_fingerprint` string, nullable
  - `next_actions` object[]

## Other responses

- `403`: Owner role required (FORBIDDEN)
- `409`: VAULT_BYO_SINGLE_WRITER — this organization owns a bring-your-own-bucket vault, which admits exactly one writer in v1 (its key envelopes live only in the customer's bucket). A developer+ add is refused by name, naming the vault in details: { storage_profile: "byo", vault_id, org_id }; no membership row, target org-of-one, or audit row is written. A viewer/billing add is unaffected — those roles confer no writer eligibility.

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)