Skip to main content

B2B organization onboarding guide

Set up reusable organization templates in the SecureAuth Connect admin UI, then use the SecureAuth System API to programmatically create organizations that inherit template configurations. This guide walks you through the complete B2B onboarding workflow: template setup, API authentication, organization creation, and verification. Use this approach to automate customer provisioning while ensuring consistent authentication methods, identity pools, and business attributes across all organizations.

Organization templates overview​

Organization templates let you define a standardized configuration for new organizations. Instead of configuring each customer organization individually, you create a template once in the UI with all desired settings. Templates capture:

Templates include:

  • Identity Pool configuration - Specifies user storage and authentication capabilities
  • Authentication methods - Define available autauthentication mechanisms (password, passkey, etc.)
  • Business attributes - Defines custom fields for organization-specific data (Salesforce ID, entitlements, etc.)

When you create a new organization via API and reference the template ID, all template configurations are automatically inherited by the new organization, ensuring consistency and reducing setup time from hours to seconds.

Example: B2B SaaS platform​

Your B2B SaaS platform serves multiple enterprise customers, each needing an isolated organization. With templates, you can streamline onboarding:

  • Create a template once with your standard B2B authentication and business attribute configuration
  • Use the API to provision new customer organizations automatically
  • Reference the template ID in each API call
  • Deliver fully configured organizations in seconds
  • Maintain consistent configuration across all customer organizations

Integration architecture​

The integration follows this high-level flow:

  1. Template setup (one-time) - Create and configure organization template in the UI.

  2. Onboarding

    • Onboard organizations as tenant administrators
    • Onboard organizations as business administrators
    • Onboard organizations using API calls

  3. Onboarding using APIs

    • Authentication - Obtain an access token using OAuth2 client credentials flow
    • Organization Creation - Use the access token to call the organization creation API with template reference

  4. Verification - Confirm organization creation and inherited configuration.

Prerequisites​

Before you start, verify you have the following:

  • SecureAuth Connect tenant
    If you don't have a tenant, set one up first.

  • System Workspace enabled
    System Workspace isn't enabled by default. Contact SecureAuth Support to enable System Workspace access for your tenant if needed.

  • Workspace enabled with at least one application
    Create a workspace and register an application. You'll need to copy the Workspace ID (in Workspace > Settings > General tab) for later use.
    To learn more, see: Create a workspace and Applications overview.

  • Your tenant information
    Gather the following before proceeding:

    • Tenant ID (found in your SecureAuth URL: https://{tenant-id}.connect.secureauth.com)
    • Region ID (found in your SecureAuth URL: https://{tenant-id}.{region-id}.connect.secureauth.com)

Step 1: Organization template setup​

Organization templates in SecureAuth are special organizations that store your standard configuration. When you create a template, you're creating an organization that holds your standard Identity Pool, authentication methods, and business attributes. You then configure this template organization just like you would a regular organization. Later, when you create new organizations via API, they inherit all the configurations from your template.

This section walks you through creating and configuring your template organization.

1.1 Create organization template​

  1. Go to Tenant Settings > Organizations > Templates. Create organization template

  2. Click CREATE TEMPLATE.

  3. Provide a name and click Create. Organization template created

Your template organization is now created. In the next steps, you'll click on this template organization and configure it just like you would configure a regular organization. The following sections walk you through configuring the Identity Pool, authentication methods, business attributes schema, and noting the template ID.

warning

This template organization is for configuration only. Do not use it for onboarding actual customers or storing customer data. Use it exclusively to define your standard B2B configuration.

1.2 Configure Identity Pool​

Identity Pools provide user storage and authentication capabilities for your organizations. Create an Identity Pool in your template so every customer organization automatically gets user management.

  1. Go to Tenant Settings > Organizations > Templates and select your organization template.

  2. In the left navigation, select Users.

  3. Click CREATE POOL. Create Identity Pool

  4. Define the Pool name and Description.

  5. Click Create.

1.3 Configure authentication methods​

For this B2B example, configure two authentication methods: Password and Passkey (WebAuthn). This provides a balance of familiarity (password) and modern security (passkey).

  1. Within your Identity Pool that you just created, click the Sign-in and Sign-up tab. Configure authentication methods

  2. Under First-Factor Authentication Methods, you'll see Password is already configured by default.

  3. Click Add method and select Passkey.

  4. Save your changes.

1.4 Configure business attributes​

Business attributes allow you to store custom organization-specific data. For B2B scenarios, you typically need to link your SecureAuth organizations to external systems like Salesforce, store entitlements, and track business metadata.

  1. In the organization template, go to Settings.

  2. Click the Custom Attributes tab. B2B schema configuration in Administrative tab

  3. Copy and paste the following JSON schema into the editor, replacing the default schema:

    {
      "properties": {
        "orgEntitlements": {
          "description": "List of features/services this organization has access to",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "region": {
          "description": "Geographic region or country",
          "type": "string"
        },
        "salesforceId": {
          "description": "Salesforce Account ID for bidirectional mapping",
          "type": "string",
          "maxLength": 18
        }
      },
      "description": "B2B Customer Organization Attributes",
      "additionalProperties": false,
      "type": "object"
    }

  4. On the right side of the editor, form fields appear for each schema property. You can enter test values in these fields to validate your schema before saving.
    It should look like the following screenshot: Paste JSON schema

Understanding the schema fields

When you paste the JSON schema, the right side of the editor displays form fields that correspond to each property in your schema. Each field shows its data type and whether it's required:

  • Salesforceid (required) - A text field that stores the Salesforce Account ID for bidirectional mapping between your SaaS platform and Salesforce.
  • orgentitlements (optional) - An array field where you list features or services this customer has access to (for example, premium, analytics, api-access).
  • Region (optional) - A text field for the geographic region or country where the organization operates, useful for compliance or routing decisions.

1.5 Note the template ID​

To retrieve your template ID, you'll need to go to the template organization's settings:

  1. In the left sidebar, scroll down and select Settings.

  2. Click the General tab.

  3. Locate the id field and copy this value. Retrieve template ID

This template ID is required when you create organizations via API - you'll pass it in the API request so new organizations inherit this template's configuration.

Your organization template is now ready! Here's what will be automatically applied to every new organization created with this template:

  • Identity pool - Enabled with user storage
  • Authentication methods - Password (preferred) and Passkey
  • Business attributes schema:
    • salesforceId (required)
    • orgEntitlements (array)
    • region

Step 2: Fetch API access token​

2.1 Configure System workspace client​

To call the organization creation API, you need to create a service client application in the System workspace. This client will use OAuth2 client credentials to obtain an access token for API authentication.

  1. Go to your System workspace. If it is not enabled on your tenant, contact SecureAuth Support.

  2. In left sidebar, go to Applications > Clients, and click Create Client.

  3. Choose a name for Application Name.

  4. In the Select Application Type section, select Service and click Create.

  5. On the Scope tab of the newly-created application, click Management and choose manage_organizations scope.

  6. Click Save.

  7. Go to the Overview tab and note:

    • Client ID
    • Client Secret
    • Token URL

2.2 Obtain access token​

Use the OAuth2 client credentials flow to obtain an access token.

Endpoint

POST {Token URL}

Headers

Content-Type: application/x-www-form-urlencoded

Request body

grant_type=client_credentials
client_id={your-client-id}
client_secret={your-client-secret}
scope=manage_organizations

Example cURL request

curl -X POST "https://{tenant-id}.{region-id}.secureauth.com/{tenant-id}/system/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=manage_organizations"

Response

{
  "access_token": "eyJhbGc...",
  "expires_in": "3600",
  "scope": "manage_organizations",
  "token_type": "Bearer"
}

The access_token is valid for expires_in seconds (in this example, 3600 seconds or 1 hour). Store this token for the next step. If the token expires during your integration, obtain a new one by repeating this request.

Step 3: Create organization with template​

Now you'll use your access token to call the organization creation API. Reference your template ID to automatically apply all template configurations to the new organization.

3.1 API endpoint details​

Endpoint

POST /api/system/{tenant-id}/organizations

Full URL

https://{tenant-id}.{region-id}.secureauth.com/api/system/{tenant-id}/organizations

Headers

Authorization: Bearer {access-token}
Content-Type: application/json

3.2 Request body schema​

FieldTypeRequiredDescription
namestringYesUnique identifier/name of the organization (URL-safe, lowercase recommended)
displayNamestringNoHuman-readable display name shown in UI
template_idstringRecommendedID of organization template to apply configuration (use b2b-customer-template)
descriptionstringNoOptional description of the organization
emailstringNoContact email for the organization
parent_idstringNoID of parent organization for hierarchical structure
metadataobjectNoCustom business attributes matching your schema (like salesforceId, orgEntitlements, etc.)
Best practice

Always include template_id to ensure consistent configuration. Without it, you'll need to manually configure the organization after creation.

3.3 Example requests​

Minimal request (with template)
This is the minimum required to create a fully configured organization:

{
  "name": "acme-corp-001",
  "displayName": "ACME Corporation",
  "template_id": "a13ee0f6236f4d7f89085945c3f75cdx"
}

Recommended request (with template and business attributes)
This includes business attributes for integration with external systems:

{
  "name": "acme-corp-001",
  "displayName": "ACME Corporation",
  "template_id": "a13ee0f6236f4d7f89085945c3f75cdx",
  "description": "ACME Corporation - Global Manufacturing",
  "email": "contact@acme.com",
  "metadata": {
    "salesforceId": "001xx000003DGb2AAG",
    "orgEntitlements": ["premium", "analytics", "api-access"],
    "region": "North America"
  }
}

cURL example

curl -X POST "https://{tenant-id}.{region-id}.secureauth.com/api/system/{tenant-id}/organizations" \
  -H "Authorization: Bearer {access-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-corp-001",
    "description": "ACME Corporation - Global Manufacturing",
    "parent_id": "{parent-org-id}",
    "template_id": "b2b-customer-template",
    "metadata": {
      "payload": {
        "salesforceId": "001xx000003DGb2AAG",
        "orgEntitlements": [
          "premium",
          "analytics"
        ],
        "region": "North America"
      }
    }
  }'

Success response (201 Created or 200 OK)

{
  "id": "c74c00101ecf45c6a08e5f4a370bd71a",
  "name": "acme-corp-001",
  "description": "ACME Corporation - Global Manufacturing",
  "parent_id": "parent-org-id",
  "color": "",
  "metadata": {
    "payload": {
      "salesforceId": "001xx000003DGb2AAG",
      "orgEntitlements": ["premium", "analytics"],
      "region": "North America"
    },
    "schema": {}
  },
  "domains": null,
  "authentication_mechanisms": null,
  "deactivated": false,
  "issuer_url": "https://{tenant-id}.{region-id}.secureauth.com/{tenant-id}/c74c00101ecf45c6a08e5f4a370bd71a",
  "theme_id": null,
  "subject_format": "",
  "subject_identifier_algorithm_salt": "",
  "template": false,
  "number_of_child_organizations": 0
}

Step 4: Verify organization creation​

  1. In the SecureAuth Connect admin portal, go to Tenant Settings > Workspaces.

  2. Find the newly-created organization and click on it to see the details.

  3. Verify template configuration was applied:

    • Go to Users, select the Sign-in and Sign-up tab; and check if Password and Passkey are enabled.
    • Go to Settings, select the Custom Attributes tab and check if the business attributes you defined in template organization exist there.

See also​

Support​

If you encounter issues or have questions about this integration: