Skip to main content

Create organizations via API

Use the SecureAuth System API to programmatically create organizations that inherit configurations from an organization template. This approach automates customer provisioning while ensuring consistent authentication methods, identity pools, and business attributes across all organizations.

Integration architecture​

  1. Template setup (one-time) – Create and configure an organization template.
  2. Authentication – Obtain an access token using the OAuth2 client credentials flow.
  3. Organization creation – Use the access token to call the organization creation API with the template reference.
  4. Verification – Confirm organization creation and inherited configuration.

Prerequisites​

  • 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)

  • Organization template Create and configure a template before using the API. See Organization templates.

Step 1: Fetch API access token​

Configure System workspace client​

To call the organization creation API, create a service client application in the System workspace. This client uses OAuth2 client credentials to obtain an access token.

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

  2. In the 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

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 2: Create organization with template​

Use your access token to call the organization creation API. Reference your template ID to automatically apply all template configurations to the new organization.

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

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.
descriptionstringNoOptional description of the organization.
emailstringNoContact email for the organization.
parent_idstringNoID of parent organization for hierarchical structure.
metadataobjectNoCustom business attributes matching your schema.
tip

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

Example requests​

Minimal request (with template)

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

Recommended request (with template and business attributes)

{
  "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 3: 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.
  3. Verify template configuration was applied:
    • Go to Users, select the Sign-in and Sign-up tab, and check if the authentication methods from your template are enabled.
    • Go to Settings, select the Custom Attributes tab, and check if the business attributes from your template exist.

See also​