Organizations

Update an organization

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.

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

Path parameters

idstring required

Request body

namestring

Legal or commercial name of the organization (e.g. Keyban SAS). Displayed in the admin UI and on invoices.

slugstring

URL-safe unique identifier of the organization in kebab-case (e.g. keyban-sas). Used in API paths and subdomains. Distinct from name.

logostring 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.

agentRolesstring[] 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.

Example request

{
  "name": "Keyban SAS",
  "slug": "keyban-sas",
  "logo": "https://cdn.example.com/logos/keyban.png",
  "defaultLocale": "fr-FR",
  "preferredCurrency": "EUR",
  "agentRoles": [
    "sales",
    "analyst"
  ],
  "settings": {
    "authConfig": {
      "auth0": {
        "clientId": "abc123xyz",
        "clientSecret": "**********",
        "domain": "keyban.eu.auth0.com"
      }
    }
  }
}

Response

Organization updated successfully

idstring uuid required

Unique identifier of the organization (UUID v4).

createdAtstring date-time required

Creation date (ISO 8601).

namestring required

Legal or commercial name of the organization (e.g. Keyban SAS). Displayed in the admin UI and on invoices.

slugstring required

URL-safe unique identifier of the organization in kebab-case (e.g. keyban-sas). Used in API paths and subdomains. Distinct from name.

logostring uri nullable required

HTTPS URL of the organization logo (PNG or SVG). null when no logo has been uploaded.

metadataobject 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.

agentRolesstring[] 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.

planIncludesTreasuryboolean 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.

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "createdAt": "2024-01-15T09:30:00.000Z",
  "name": "Keyban SAS",
  "slug": "keyban-sas",
  "logo": "https://cdn.example.com/logos/keyban.png",
  "defaultLocale": "fr-FR",
  "preferredCurrency": "EUR",
  "agentRoles": [
    "sales",
    "analyst"
  ],
  "acquisitionChannel": "n8n",
  "planIncludesTreasury": true,
  "settings": {
    "authConfig": {
      "auth0": {
        "clientId": "abc123xyz",
        "clientSecret": "**********",
        "domain": "keyban.eu.auth0.com"
      }
    }
  },
  "quotas": {
    "applicationLimit": 5,
    "trustProductLimit": 5,
    "trustAuditLimit": 10,
    "dppMonthlyLimit": 10000,
    "activeUsersMonthlyLimit": 50000,
    "agentWalletLimit": 10,
    "transactionLimit": 2000,
    "chargebee": {
      "customerId": "cbdemo_AzqhKqSU6HrW1Mvq",
      "subscriptionId": "AzZlGzSU6c6Hqxwh"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.