---
title: "Update an organization"
method: PATCH
path: "/v1/organizations/{id}"
tags: ["Organizations"]
---

# Update an organization

`PATCH /v1/organizations/{id}`

## Request

- Base URL: `https://api.prod.keyban.io`
- URL: `https://api.prod.keyban.io/v1/organizations/{id}`
- Auth: API key in header `X-Api-Key`

Update mutable fields and settings of the **active** organization (the path `id` must match the requesting org). Requires the `settings:update` permission. This endpoint cannot edit a different organization, even with super admin access. `preferredCurrency` is write-once: it can be set while null and re-sent unchanged, but never changed afterwards — sending `null` leaves it untouched.

## Path parameters

- `id` string, required

## Request body

- UpdateOrganizationDto
  - `name` string: Legal or commercial name of the organization (e.g. `Keyban SAS`). Displayed in the admin UI and on invoices.
  - `slug` string: URL-safe unique identifier of the organization in kebab-case (e.g. `keyban-sas`). Used in API paths and subdomains. Distinct from `name`.
  - `logo` string, uri, nullable: HTTPS URL of the organization logo (PNG or SVG). `null` when no logo has been uploaded.
  - `defaultLocale` 'en-US' | 'fr-FR' | 'es-ES' | 'it-IT' | 'null', nullable: BCP 47 language tag for the organization's default locale (e.g. `fr-FR`). Null when not set; falls back to Accept-Language header.
  - `preferredCurrency` 'EUR' | 'USD' | 'JPY' | 'null', nullable: Fiat currency (ISO 4217) the organization displays monetary values in: wallet and treasury balances are converted to it, transfer amounts are quoted in it for signers, and agent spending policies are authored in it. Chosen once, at the creation of the first application or treasury, and immutable afterwards (a change is refused with `ORG_PREFERRED_CURRENCY_IMMUTABLE`; sending `null` or omitting the field leaves it untouched). Null until chosen.
  - `agentRoles` string[], nullable: What the organization's agents do, as picked during the agent-wallet onboarding. Selects the example prompts offered for the first payment. Null until picked.
  - `settings` object
    - `authConfig` object, required
      - `email-otp` union, required
        - object
          - `enabled` true, required: Authentication method is active for this organization.
        - object
          - `enabled` false, required: Authentication method is disabled for this organization.
      - `phone-otp` union, required
        - object
          - `enabled` true, required: Authentication method is active for this organization.
        - object
          - `enabled` false, required: Authentication method is disabled for this organization.
      - `google` union, required
        - object
          - `enabled` true, required: Authentication method is active for this organization.
        - object
          - `enabled` false, required: Authentication method is disabled for this organization.
      - `auth0` union, required
        - object
          - `enabled` true, required: Authentication method is active for this organization.
          - `clientId` string, required: OAuth 2.0 / OIDC client identifier issued by the Auth0 tenant. Required when Auth0 is enabled.
          - `clientSecret` string, required: OAuth 2.0 / OIDC client secret issued by the Auth0 tenant. Sensitive — excluded from public API responses via `.omit` in `application/index.ts`. Never log or expose this value.
          - `domain` string, required: Auth0 tenant domain used as the OIDC issuer base URL (e.g. `keyban.eu.auth0.com`). Required when Auth0 is enabled.
        - object
          - `enabled` false, required: Authentication method is disabled for this organization.

## Response `200`

Organization updated successfully

- AuthOrganizationDtoOutput
  - `id` string, uuid, required: Unique identifier of the organization (UUID v4).
  - `createdAt` string, date-time, required: Creation date (ISO 8601).
  - `name` string, required: Legal or commercial name of the organization (e.g. `Keyban SAS`). Displayed in the admin UI and on invoices.
  - `slug` string, required: URL-safe unique identifier of the organization in kebab-case (e.g. `keyban-sas`). Used in API paths and subdomains. Distinct from `name`.
  - `logo` string, uri, nullable, required: HTTPS URL of the organization logo (PNG or SVG). `null` when no logo has been uploaded.
  - `metadata` object, nullable, required: Billing and onboarding state managed by Keyban (Chargebee subscription, trial and pending markers). Read-only and ignored on update; its keys may change without notice.
  - `defaultLocale` 'en-US' | 'fr-FR' | 'es-ES' | 'it-IT' | 'null', nullable: BCP 47 language tag for the organization's default locale (e.g. `fr-FR`). Null when not set; falls back to Accept-Language header.
  - `preferredCurrency` 'EUR' | 'USD' | 'JPY' | 'null', nullable: Fiat currency (ISO 4217) the organization displays monetary values in: wallet and treasury balances are converted to it, transfer amounts are quoted in it for signers, and agent spending policies are authored in it. Chosen once, at the creation of the first application or treasury, and immutable afterwards (a change is refused with `ORG_PREFERRED_CURRENCY_IMMUTABLE`; sending `null` or omitting the field leaves it untouched). Null until chosen.
  - `agentRoles` string[], nullable: What the organization's agents do, as picked during the agent-wallet onboarding. Selects the example prompts offered for the first payment. Null until picked.
  - `acquisitionChannel` 'n8n' | 'trial' | 'null', nullable: Third-party channel the organization signed up through (e.g. the n8n node listing). Null for an organic/direct signup, never attributed to a specific channel.
  - `planIncludesTreasury` boolean, required: Whether the current plan includes the organization treasury (Agent Wallet Growth and above). Creating a treasury needs this or a Keyban grant (`quotas.pilotFeatures`); a treasury already created stays usable either way.
  - `settings` object, required
    - `authConfig` object, required
      - `email-otp` union, required
        - object
          - `enabled` true, required: Authentication method is active for this organization.
        - object
          - `enabled` false, required: Authentication method is disabled for this organization.
      - `phone-otp` union, required
        - object
          - `enabled` true, required: Authentication method is active for this organization.
        - object
          - `enabled` false, required: Authentication method is disabled for this organization.
      - `google` union, required
        - object
          - `enabled` true, required: Authentication method is active for this organization.
        - object
          - `enabled` false, required: Authentication method is disabled for this organization.
      - `auth0` union, required
        - object
          - `enabled` true, required: Authentication method is active for this organization.
          - `clientId` string, required: OAuth 2.0 / OIDC client identifier issued by the Auth0 tenant. Required when Auth0 is enabled.
          - `clientSecret` string, required: OAuth 2.0 / OIDC client secret issued by the Auth0 tenant. Sensitive — excluded from public API responses via `.omit` in `application/index.ts`. Never log or expose this value.
          - `domain` string, required: Auth0 tenant domain used as the OIDC issuer base URL (e.g. `keyban.eu.auth0.com`). Required when Auth0 is enabled.
        - object
          - `enabled` false, required: Authentication method is disabled for this organization.
  - `quotas` object, required: Quotas, entitlements and current usage of the organization. The same record as `GET /v1/quotas/{orgId}`, keyed by the organization.
    - `applicationLimit` integer, nullable: Maximum number of applications the organization is allowed to own concurrently. `null` means unlimited (no quota enforced).
    - `trustProductLimit` integer, nullable: Maximum number of published products the organization is allowed to own concurrently. `null` means unlimited (no quota enforced).
    - `trustAuditLimit` integer, nullable: Maximum number of tracked AI-visibility audit subjects the organization may hold concurrently. Defaults to 10 when `null`.
    - `dppMonthlyLimit` integer, nullable: Maximum number of Digital Product Passports that can be minted within a single calendar month. Resets on the first day of each month. `null` means unlimited.
    - `activeUsersMonthlyLimit` integer, nullable: Maximum number of distinct end-users who can interact with the organization’s applications within a calendar month. Resets monthly. `null` means unlimited.
    - `agentWalletLimit` integer, nullable: Maximum number of agent wallets the organization may hold concurrently (total, not monthly). `null` means unlimited (no cap enforced).
    - `transactionLimit` integer, nullable: Maximum number of agent wallet transactions (consumed intents) per calendar month, across all applications of the organization. Resets on the first day of each month (UTC). `null` means unlimited (no cap enforced).
    - `chargebee` object, required: Billing identifiers mirrored from Chargebee. Used to reconcile usage with invoicing; the source of truth for billing state remains Chargebee.
      - `customerId` string, nullable: Chargebee customer identifier linked to the organization. `null` when no billing profile exists yet (e.g. free tier before onboarding completion).
      - `subscriptionId` string, nullable: Active Chargebee subscription identifier for the organization. `null` when the organization has no active subscription.
    - `allowOverage` boolean, required: When `true`, usage is allowed to exceed the configured limits and any overage is billed through Chargebee. When `false`, requests that would exceed a limit are rejected with a quota error.
    - `allowTransactionOverage` boolean, required: When `true`, the organization may choose to keep transacting beyond `transactionLimit` and be billed per extra transaction. Always `false` on the free plan, which blocks at the limit.
    - `blockOnTransactionQuota` boolean, required: When `true`, agent transactions are refused once `transactionLimit` is reached. When `false` (and `allowTransactionOverage` is `true`), extra transactions are billed.
    - `transactionAlertRecipientIds` string[], required: Identifiers of the organization members notified by e-mail when transaction usage reaches 80 % and 100 % of `transactionLimit`. Empty means no e-mail.
    - `allowedFeatures` string[], required: Technical features the organization is entitled to enable on its applications (e.g. DPP, Loyalty, Invest). Derived from the subscribed plan.
    - `pilotFeatures` string[], required: Features granted manually by a super-admin, per organization (pilot programs). Never derived from the plan: plan syncs overwrite `allowedFeatures` but must not touch this list. Entitlement checks use the union of both lists. The treasury also comes with the Agent Wallet Growth plan and above (`planIncludesTreasury` on the organization).
    - `allowedNetworks` string[], required: Blockchain networks available to the organization. Restricts the choices offered when creating applications or passports.
    - `transactionMonthlyUsage` integer, required: Number of agent wallet transactions consumed so far in the current calendar month (UTC), across all applications of the organization. Compared against `transactionLimit`.
    - `applicationUsage` integer, required: Current number of applications owned by the organization. Compared against `applicationLimit` to decide whether a new application can be created.
    - `trustProductUsage` integer, required: Number of Product published so far. Compared against `trustProductLimit`.
    - `dppMonthlyUsage` integer, required: Number of Digital Product Passports minted so far during the current calendar month. Compared against `dppMonthlyLimit`; resets monthly.
    - `activeUsersMonthlyUsage` integer, required: Number of distinct active end-users counted so far during the current calendar month. Compared against `activeUsersMonthlyLimit`; resets monthly.
    - `agentWalletUsage` integer, required: Current number of non-deleted agent wallets owned by the organization. Compared against `agentWalletLimit`.

## Other responses

- `400`: Validation error on the request body
- `403`: Forbidden — caller targets a different organization
- `422`: The display currency is already set to another value

---

[API](https://skmtc.dev/keyban/apis/keyban-rest-apis.md) · [All operations](https://skmtc.dev/keyban/apis/keyban-rest-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/keyban/apis/keyban-rest-apis/revisions/0bb79a1da961?raw)