1. Organizations
  2. Create & Update Organizations

Organizations

Create & Update Organizations

Create Organization

INFO

You should only create an organization via API key if you are an enterprise customer looking to create a multi-organization setup. Please note there can be significant costs associated with this setup, so please reach out to your account manager if you are interested in this.

Creates a new organization in the PackageX platform. This endpoint serves two distinct purposes:

  • Creating tenant organizations (when called with an API key)
  • Creating standalone organizations
POST
`/v1/organizations`

Enterprise Tenant Creation

When using an API key, this endpoint creates a tenant organization managed by your enterprise organization. Your organization must be on an enterprise plan to create tenants. Each tenant organization maintains separate data but billing is handled through the parent organization.

Request Body

js 
        {
  user: {
    email: string,     // Required: Owner's email address
    name: string,      // Required: Owner's name
  },
  organization: {
    name: string,      // Required: Organization name (max 30 characters)
    address: string,   // Required for tenants: Physical address
  }
}

Organization Setup

The endpoint configures:

  • Organization settings (deliveries, shipments, notifications, etc.)
  • Billing configuration
  • User roles (Owner and User with predefined permissions)
  • Initial wallet
  • Organization logo (auto-generated)
  • Base location (for tenant organizations)

Role Configuration

Two default roles are created:

  1. Owner Role:
    • Full system access
    • Cannot be removed
    • Manages organization settings
  2. User Role:
    • Limited permissions
    • Customizable access levels
    • Standard operational capabilities

Example Request

js 
        const data = {
  user: {
    email: "jamie@packagex.io",
    name: "Jamie Jones",
  },
  organization: {
    name: "Logistics Hub East",
    address: "500 7th Ave, New York, NY 10018",
  },
};

const response = await fetch("https://api.packagex.io/v1/organizations", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

const result = await response.json();
const organization = result.data;
const api_key = result.data.api_key;

Update Organization and it's settings

POST
`/v1/organizations/:organization`

OR

POST
`/v1/org`

When updating an organization, you can either user the full organization ID in proper RESTful fashion, or you can use the org shortcut since your API key is scoped to the organization anyway. Besides billing, every other property for the organization can be updated in the same structure as the model.

Any properties that have deeply nested lists with objects inside of them including settings.deliveries.rate_classes, settings.deliveries.private_rates, and settings.fulfillments.predefined_packages, have their own RESTful endpoints to make creating, updating, and deleting them easier.

js 
        {
  profile?: {
    name?: string,
    dba_name?: string,
    email?: string,
    phone?: string,
    website?: string,
    address?: string,
    address_line2?: string
  },
  social_media?: {
    facebook?: string,
    instagram?: string,
    linkedin?: string,
    tiktok?: string,
    twitter?: string,
    youtube?: string
  },
  settings?: {
    shipments?: {
      service_levels?: string[],
      labels?: {
        size?: "4x6" | "letter",
        format?: "pdf",
        autoprint?: boolean
      },
      defaults?: {
        parcel?: {
          height?: number,
          width?: number,
          length?: number,
          weight?: number,
          type?: string
        },
        recipient?: {
          name?: string,
          phone?: string,
          email?: string,
          address?: string
        },
        sender?: {
          name?: string,
          phone?: string,
          email?: string,
          address?: string
        },
        return_other_rates?: boolean
      },
      upcharging?: {
        active?: boolean,
        min?: number,
        max?: number,
        percent?: number,
        multiplier?: number,
        model?: "percent" | "curve"
      }
    },
    deliveries?: {
      lead_time_mins?: number,
      support_email?: string,
      support_phone?: string,
      support_url?: string,
      default_rate_id?: string,
      chaining?: {
        default_status?: string,
        reuse_tracking_number?: boolean,
        label_size?: "4x6" | "letter",
        default_parcel?: {
          height?: number,
          width?: number,
          length?: number,
          weight?: number
        }
      }
    },
    fulfillments?: {
      allow_partial?: boolean,
      check_inventory?: boolean,
      require_pick_step?: boolean,
      check_parcel_weight?: boolean,
      new_packing_slip_on_partial?: boolean,
      next_order_number?: string,
      lead_time_mins?: number,
      service_levels?: string[],
      packing_slip?: {
        size?: "letter" | "4x6",
        message?: string
      }
    },
    manifests?: {
      verify_addresses?: boolean,
      create_trackers?: boolean,
      special_handling_tags?: string[],
      next_manifest_number?: string
    },
    recipient_notifications?: {
      tracking_statuses?: string[],
      methods?: ("email" | "sms")[],
      delay_mins?: number,
      use_batches?: boolean,
      email_template?: {
        use_logo?: boolean,
        use_name?: boolean,
        use_social_media?: boolean
      },
      pickup_reminders?: {
        interval_mins?: number,
        max_count?: number,
        check_contact_availability?: boolean,
        check_location_availability?: boolean
      },
      curbside_pickup?: {
        message_template?: string,
        reply_trigger?: string
      }
    },
    contacts?: {
      create_via_recipient?: boolean
    },
    locations?: {
      layouts?: {
        locked?: boolean
      }
    },
    login?: {
      login_sso_required_preference?: "allow_all_except_blocked" | "block_all_except_allowed",
      logout_after_hours?: number,
      logout_after_inactivity_hours?: number
    },
    sdk?: {
      processing_preference?: "in_cloud" | "on_device",
      model_size_preference?: string,
      model_dynamic_selection?: string,
      model_static_fallback?: string
    },
    events?: {
      expire_after?: string
    },
    exports?: {
      expire_after?: string,
      resources?: {
        contact?: { columns?: string[] },
        fulfillment?: { columns?: string[] },
        group?: { columns?: string[] },
        item?: { columns?: string[] },
        location?: { columns?: string[] },
        manifest?: { columns?: string[] },
        shipment?: { columns?: string[] },
        tracker?: { columns?: string[] },
        asset?: { columns?: string[] }
      }
    }
  }
}

const res = await fetch(`https://api.packagex.io/v1/organizations/${org_id}`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

Example Request

js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    profile: {
      name: "Updated Organization Name",
      email: "contact@organization.com",
    },
    settings: {
      shipments: {
        labels: {
          size: "4x6",
          autoprint: true,
        },
      },
      recipient_notifications: {
        methods: ["email"],
        delay_mins: 30,
      },
    },
  }),
});

const result = await response.json();

Create / Update roles

Creates a new role or updates an existing role within your organization. This endpoint provides comprehensive control over role configurations, permissions.

POST
`/v1/organizations/:organization/roles/:role_id?`

OR

POST
`/v1/org/roles/:role_id?`

Request Body Structure

js 
        {
  name: string,                   // Required: Role name
  scopes?: {                      // Optional: Permission scopes
    organizations?: "read" | "write" | null,
    shipments?: "read" | "write" | null,
    locations?: "read" | "write" | null,
    users?: "read" | "write" | null,
    payments?: "read" | "write" | null,
    // ... other available scopes
  },
  hidden_ui_sections?: string[] | {  // Optional: UI visibility controls
    add?: string[],              // Sections to hide
    remove?: string[]            // Sections to show
  }
}

Example Requests

  1. Creating a New Role:
js 
        const response = await fetch("https://api.packagex.io/v1/organizations/roles", {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Warehouse Manager",
    scopes: {
      shipments: "write",
      locations: "write",
      items: "write",
      users: "read",
    },
    hidden_ui_sections: ["billing", "api_keys"],
  }),
});
  1. Updating an Existing Role:
js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/roles/${role_id}`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Senior Warehouse Manager",
    hidden_ui_sections: {
      remove: ["billing"], // Show billing section
    },
  }),
});

Update Payout Profile

Updates an organization's payout profile.

POST
`/v1/organizations/:organization/payouts`

OR

POST
`/v1/org/payouts`

Request Body Structure

js 
        {
  company: {
    profile: {
      name: string,         // Company legal name
      email: string,        // Business email
      phone: string,        // Business phone
      website: string,      // Company website
      address: string,      // Physical address
      address_line2?: string // Optional address details
    },
    structure: "individual" | "single_member_llc" | "multi_member_llc" |
               "private_partnership" | "private_corporation" |
               "unincorporated_association",
    tax_id: string         // Company tax ID (EIN)
  },
  representative: {
    first_name: string,
    last_name: string,
    email: string,
    phone: string,
    title: string,
    relationship: "owner" | "executive" | "representative",
    dob: string,           // Date of birth (ISO format)
    ssn_last_4: string,    // Last 4 digits of SSN
    address: string,
    address_line2?: string
  },
  owner?: {               // Required for certain company structures
    [key: string]: {      // Multiple owners supported
      first_name: string,
      last_name: string,
      email: string,
      phone: string,
      title: string,
      relationship: "owner",
      dob: string,
      ssn_last_4: string,
      address: string,
      address_line2?: string
    }
  },
  bank_account: {
    account_holder_name: string,
    routing_number: string,
    account_number: string
  }
}

Example Request

js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${organization_id}/payouts`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    company: {
      profile: {
        name: "Logistics Pro LLC",
        email: "finance@logisticspro.com",
        phone: "+1234567890",
        website: "https://logisticspro.com",
        address: "123 Business Ave, New York, NY 10001",
      },
      structure: "multi_member_llc",
      tax_id: "12-3456789",
    },
    representative: {
      first_name: "John",
      last_name: "Doe",
      email: "john@logisticspro.com",
      phone: "+1234567890",
      title: "CEO",
      relationship: "owner",
      dob: "1980-01-01",
      ssn_last_4: "1234",
      address: "456 Home St, New York, NY 10002",
    },
    owner: {
      owner1: {
        first_name: "Jane",
        last_name: "Smith",
        email: "jane@logisticspro.com",
        phone: "+1987654321",
        title: "COO",
        relationship: "owner",
        dob: "1982-03-15",
        ssn_last_4: "5678",
        address: "789 Partner Ave, New York, NY 10003",
      },
      owner2: {
        first_name: "Michael",
        last_name: "Johnson",
        email: "michael@logisticspro.com",
        phone: "+1555123456",
        title: "CFO",
        relationship: "owner",
        dob: "1979-11-20",
        ssn_last_4: "9012",
        address: "321 Investor St, New York, NY 10004",
      },
    },
    bank_account: {
      account_holder_name: "Logistics Pro LLC",
      routing_number: "110000000",
      account_number: "000123456789",
    },
  }),
});

Update External Payout Account

Updates or adds a bank account for receiving payouts through Stripe.

POST
`/v1/organizations/:organization/payouts/external-account`

OR

POST
`/v1/org/payouts/external-account`

Request Body Structure

js 
        {
  account_number: string,    // Full bank account number
  routing_number: string     // Bank routing number
}

Example Request

js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${organization_id}/payouts/external-account`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    account_number: "000123456789",
    routing_number: "110000000",
  }),
});

Updates an organization's logo.

POST
`/v1/organizations/:organization/logo`

OR

POST
`/v1/org/logo`

Request Body Structure

js 
        {
  logo_url: string; // Required: URL or base64 data of the logo image
}

Example Request

js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${organization_id}/logo`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    logo_url: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", // Base64 image data
  }),
});

Create/Update Delivery Rate

This endpoint manages delivery rate configurations for organizations, enabling the creation of new rates and modification of existing ones

POST
`/v1/organizations/:organization/settings/deliveries/rates/:rate_id?`

OR

POST
`/v1/org/settings/deliveries/rates/:rate_id?`

Request Body Structure

The endpoint accepts a comprehensive rate configuration object:

js 
        {
  name: string,                // Required: Descriptive name for the rate
  service_level: string,       // Required: Delivery service level
  length?: number,             // Package length in cm (default: 100)
  width?: number,              // Package width in cm (default: 100)
  height?: number,             // Package height in cm (default: 100)
  weight?: number,             // Package weight in kg (default: 100)
}

Example Requests

  1. Creating a New Rate:
js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/settings/deliveries/rates`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Standard Delivery",
    service_level: "ground",
    length: 50,
    width: 30,
    height: 20,
    weight: 5,
  }),
});
  1. Updating an Existing Rate:
js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/settings/deliveries/rates/${rate_id}`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Premium Delivery",
    service_level: "express",
    weight: 10,
  }),
});

Create/Update Delivery Rate Package

This endpoint manages package configurations associated with delivery rates, enabling organizations to define specific package dimensions, and weights for each delivery rate.

POST
`/v1/organizations/:organization/settings/deliveries/rates/:rate/packages/:package_id?`

OR

POST
`/v1/org/settings/deliveries/rates/:rate/packages/:package_id?`

Request Body Structure

js 
        {
  length: number,           // Required: Package length (integer)
  width: number,           // Required: Package width (integer)
  height: number,          // Required: Package height (integer)
  weight: number,          // Required: Package weight (integer)
  active?: boolean,        // Optional: Package availability status (default: true)
  pickup_fee?: number,     // Optional: Base fee for pickup (integer, default: 0)
  pickup_rate?: number,    // Optional: Rate per unit for pickup (integer, default: 0)
  dropoff_fee?: number,    // Optional: Base fee for dropoff (integer, default: 0)
  dropoff_rate?: number,   // Optional: Rate per unit for dropoff (integer, default: 0)
  return_fee?: number,     // Optional: Fee for returns (integer, default: 0)
  discount_percent?: number // Optional: Applied discount percentage (default: 0)
}

Example Requests

  1. Creating a New Package Configuration:
js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}settings/deliveries/rates/:rate/packages`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    length: 50,
    width: 30,
    height: 20,
    weight: 5,
    pickup_fee: 500,
    dropoff_fee: 300,
    discount_percent: 10,
  }),
});
  1. Updating an Existing Package:
js 
        const response = await fetch(
  `https://api.packagex.io/v1/organizations/${org_id}/settings/deliveries/rates/:rate/packages/${package_id}`,
  {
    method: "PUT",
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      weight: 10,
      pickup_rate: 100,
      active: false,
    }),
  }
);

Create/Update Predefined Package

This endpoint manages predefined package configurations for organizations, enabling the creation and modification of standardized package templates.

POST
`/v1/organizations/:organization/settings/fulfillments/predefined-packages`

OR

POST
`/v1/org/settings/fulfillments/predefined-packages`

Request Body Structure

js 
        {
  id?: string,                         // Optional: Package identifier
  name?: string,                       // Optional: Package name (max 250 chars)
  type?: string,                       // Optional: Provider package type
  length?: number,                     // Package length
  width?: number,                      // Package width
  height?: number,                     // Package height
  max_weight_domestic?: number,        // Maximum domestic weight (default: 50)
  max_weight_international?: number    // Maximum international weight (default: 50)
}

Example Requests

  1. Creating a Custom Package:
js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/settings/fulfillments/predefined-packages`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Standard Box",
    length: 30,
    width: 20,
    height: 15,
    max_weight_domestic: 40,
    max_weight_international: 35,
  }),
});
  1. Using a Provider Package Template:
js 
        const response = await fetch(
  `https://api.packagex.io/v1/organizations/${org_id}/settings/fulfillments/predefined-packages/${package_id}`,
  {
    method: "PUT",
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "PROVIDER_STANDARD_BOX",
    }),
  }
);

Update Shipment Provider

This endpoint manages shipment provider configurations for organizations.

POST
`/v1/organizations/:organization/providers/:provider`

OR

POST
`/v1/org/providers/:provider`

Request Body Structure

The endpoint accepts provider configuration updates in two formats for flexibility:

  • Standard Format:
js 
        {
  active: boolean,        // Provider activation status
  rate_card?: string     // Optional rate card identifier
}
  • Alternative Format (Nested Structure):
js 
        {
  settings: {
    shipments: {
      providers: {
        [provider_id]: {
          active: boolean,
          rate_card?: string
        }
      }
    }
  }
}

Example Requests

  1. Activating a Provider:
js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/providers/${provider_id}`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    active: true,
    rate_card: "standard_rates_2024",
  }),
});
  1. Deactivating a Provider:
js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/providers/${provider_id}`, {
  method: "PUT",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    active: false,
  }),
});

Create Organization Notification Rules

This endpoint enables organizations to establish and manage notification rules, controlling how and when notifications are triggered within their organization

POST
`/v1/organizations/:organization/notification-rules`

OR

POST
`/v1/org/notification-rules`

Request Body Structure

js 
        {
  rules: [{
    event: string,                // Event trigger identifier
    channels: [{
      type: string,              // Notification channel type
      template: string,          // Message template identifier
      recipients: [{
        type: string,            // Recipient type
        id?: string,             // Optional recipient identifier
        email?: string,          // Optional email address
        phone?: string           // Optional phone number
      }],
      conditions?: [{       // Optional triggering conditions
        field: string,           // Condition field
        operator: string,        // Comparison operator
        value: any              // Comparison value
      }]
    }]
  }]
}

Example Request

js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/notification-rules`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    rules: [
      {
        event: "shipment.delivered",
        channels: [
          {
            type: "email",
            template: "delivery_confirmation",
            recipients: [
              {
                type: "user",
                email: "operations@company.com",
              },
            ],
            conditions: [
              {
                field: "value",
                operator: "greater_than",
                value: 1000,
              },
            ],
          },
        ],
      },
    ],
  }),
});

Create Organization Domain

This endpoint enables organizations to establish and manage domain configurations for their login settings.

POST
`/v1/organizations/:organization/settings/login/domains`

OR

POST
`/v1/org/settings/login/domains`

Request Body Structure

js 
        {
  name: string,                        // Domain name to be registered
  status: "owned" | "blocked" | "allowed", // Domain status type
  profile_require_approval?: boolean,   // Whether new profiles require approval
  profile_role_id_default?: string     // Default role ID for new profiles
}

Example Request

js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/settings/login/domains`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "company.com",
    status: "owned",
    profile_require_approval: true,
    profile_role_id_default: "role_standard_user",
  }),
});

Updating Organization Domain

This endpoint allows organizations to modify existing domain configurations within their login settings.

POST
`/v1/organizations/:organization/settings/login/domains/:domain`

OR

POST
`/v1/org/settings/login/domains/:domain`

Request Body Structure

js 
        {
  status?: "owned" | "blocked" | "allowed",  // Modified domain status
  profile_require_approval?: boolean,         // Updated approval requirement
  profile_role_id_default?: string           // New default role assignment
}

Example Request

js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/settings/login/domains/${domain_id}`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    status: "allowed",
    profile_require_approval: true,
    profile_role_id_default: "role_standard",
  }),
});

Create Organization SSO Configuration

This endpoint enables organizations to establish Single Sign-On (SSO) configurations for their verified domains.

POST
`/v1/organizations/:organization/settings/login/sso`

OR

POST
`/v1/org/settings/login/sso`

Request Structure

The endpoint accepts two distinct configuration formats based on the authentication protocol:

  1. For OpenID Connect (OIDC):
js 
        {
  name: string,                    // 5-50 characters, lowercase
  type: "oidc",
  identity_provider: "azure" | "okta" | "google" | "custom",
  domains: [{
    id: string,
    name: string
  }],
  idp_oidc_client_id: string,     // Maximum 1023 characters
  idp_oidc_issuer_url: string,    // Valid URL format
  idp_oidc_client_secret?: string // Optional, maximum 1023 characters
}
  1. For SAML:
js 
        {
  name: string,                    // 5-50 characters, lowercase
  type: "saml",
  identity_provider: "azure" | "okta" | "google" | "custom",
  domains: [{
    id: string,
    name: string
  }],
  idp_saml_entity_id: string,     // Maximum 1023 characters
  idp_saml_sso_url: string,       // Valid URL format
  idp_saml_certificate: string    // Valid X.509 certificate format
}

Example Request

js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/settings/login/sso`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Corporate SSO",
    type: "saml",
    identity_provider: "okta",
    domains: [
      {
        id: "dom_123",
        name: "company.com",
      },
    ],
    configuration: {
      issuer: "https://identity.company.com",
      sign_in_endpoint: "https://identity.company.com/login",
      certificate: "-----BEGIN CERTIFICATE-----\n...",
    },
  }),
});

Update Organization SSO Configuration

This endpoint enables organizations to modify existing Single Sign-On (SSO) configurations.

POST
`/v1/organizations/:organization/settings/login/sso/:sso_id`

OR

POST
`/v1/org/settings/login/sso/:sso_id`

Request Structure

The endpoint accepts protocol-specific update configurations:

  1. For OpenID Connect (OIDC):
js 
        {
  type: "oidc",
  idp_oidc_client_id?: string,        // Optional update, max 1023 chars
  idp_oidc_issuer_url?: string,       // Optional update, valid URL
  idp_oidc_client_secret?: string,    // Optional update, max 1023 chars
  domains: Array[{                     // Required domain associations
    id: string,
    name: string
  }]
}
  1. For SAML:
js 
        {
  type: "saml",
  idp_saml_entity_id?: string,        // Optional update, max 1023 chars
  idp_saml_sso_url?: string,          // Optional update, valid URL
  idp_saml_certificate?: string,       // Optional update, valid certificate
  domains: [{                     // Required domain associations
    id: string,
    name: string
  }]
}

Example Request

js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/settings/login/sso/${sso_id}`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Corporate SSO",
    type: "saml",
    identity_provider: "okta",
    domains: [
      {
        id: "dom_123",
        name: "company.com",
      },
    ],
    configuration: {
      issuer: "https://identity.company.com",
      sign_in_endpoint: "https://identity.company.com/login",
      certificate: "-----BEGIN CERTIFICATE-----\n...",
    },
  }),
});

Apply Organization Login Settings

This endpoint enables organizations to enforce their login domain preferences.

POST
`/v1/organizations/:organization/settings/login/apply`

OR

POST
`/v1/org/settings/login/apply`

Request Structure

js 
        {
  apply_login_settings: boolean,               // Whether to apply changes
  test_email_address_against_login_settings?:  // Optional email for testing
    string                                     // Must be valid email format
}

Example Usage

  • Testing Domain Policy:
js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/settings/login/apply`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    apply_login_settings: false,
    test_email_address_against_login_settings: "user@example.com",
  }),
});
  • Applying Domain Policy:
js 
        const response = await fetch(`https://api.packagex.io/v1/organizations/${org_id}/settings/login/apply`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    apply_login_settings: true,
  }),
});
Previous <- Model
Next Retrieve Organizations ->