UpsertOrganizationAuthKitParams

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/picaos/main/json-schema/picaos-upsert-organization-auth-kit-params-schema.json",
  "title": "UpsertOrganizationAuthKitParams",
  "description": "Request body for `PUT\n/v1/management/organizations/{org_id}/authkit`.",
  "x-generated": "2026-10-21",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/picaos-api-openapi.json#/components/schemas/UpsertOrganizationAuthKitParams",
  "additionalProperties": false,
  "properties": {
    "active": {
      "description": "Whether this OAuth configuration is enabled. When `false` the\nplatform is hidden from the Embeddable Auth picker for end\nusers in this scope and environment, even if credentials are\npresent.",
      "type": "boolean"
    },
    "clientId": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/NonEmptyString",
          "description": "OAuth 2.0 client ID issued by the platform's developer console\nfor your OAuth app. Required when `useDefaultOauthCreds` is\nfalse or omitted. Ignored when `useDefaultOauthCreds` is true."
        }
      ]
    },
    "clientSecret": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "$ref": "#/$defs/NonEmptyString",
          "description": "OAuth 2.0 client secret paired with `clientId`. Stored\nencrypted at rest and never returned in responses. Required\nwhen `useDefaultOauthCreds` is false or omitted. Ignored when\n`useDefaultOauthCreds` is true."
        }
      ]
    },
    "connectionDefinitionId": {
      "$ref": "#/$defs/ConnectionDefinitionId"
    },
    "environment": {
      "$ref": "#/$defs/SecretKeyEnvironment",
      "description": "Which environment (`test` or `live`) this configuration\napplies to. Each environment has its own row, so a test OAuth\napp and a live OAuth app can coexist for the same platform."
    },
    "guide": {
      "description": "Optional URL shown behind the \"View connection guide\" link in\nthe Embeddable Auth component for this platform. Typically a\npage in your docs explaining how end users should obtain\nwhatever the platform requires (account, workspace, etc.)\nbefore connecting. Must be an absolute `http://` or `https://`\nURL; other schemes (`javascript:`, `data:`, `file:`, …) are\nrejected to prevent stored-XSS / phishing on dashboards and\nthe AuthKit widget that render this value as a clickable link.",
      "type": [
        "string",
        "null"
      ]
    },
    "scopes": {
      "description": "Space-separated list of OAuth scopes to request from the\nplatform (RFC 6749 §3.3 format, e.g.\n`\"read:user offline_access\"`). Applied to both the\nauthorization-URL `scope` parameter and the client-credentials\ntoken exchange. Leave unset to use the platform's default\nscope set.",
      "type": [
        "string",
        "null"
      ]
    },
    "useDefaultOauthCreds": {
      "description": "When `true`, use Pica's managed OAuth app for this platform\ninstead of supplying your own `clientId` and `clientSecret`.",
      "type": [
        "boolean",
        "null"
      ]
    }
  },
  "required": [
    "connectionDefinitionId",
    "environment",
    "active"
  ],
  "type": "object",
  "$defs": {
    "ConnectionDefinitionId": {
      "description": "Prefixed ID with 'conn_def' prefix (e.g., 'conn_def_1C'), also accepts raw integer",
      "type": "string"
    },
    "NonEmptyString": {
      "type": "string"
    },
    "SecretKeyEnvironment": {
      "enum": [
        "test",
        "live"
      ],
      "type": "string"
    }
  }
}