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, user populations, 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. Send the request to the Token URL of your client:

curl -X POST "https://{tenant-id}.{region-id}.connect.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}.connect.secureauth.com/api/system/{tenant-id}/organizations

Headers

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

Request body schema​

FieldTypeRequiredDescription
idstringNoUnique identifier of the organization. Used in URLs and API calls, and can't be changed later. A random ID is generated if you omit it.
namestringRecommendedDisplay name of the organization.
template_idstringRecommendedID of the organization template to copy configuration from. Without it, the organization has no user population or sign-in configuration until you add them.
descriptionstringNoDescription of the organization.
domainsarray of stringsNoEmail domains used to route users to this organization at sign-in.
parent_idstringRecommendedID of the parent workspace or organization. Without it, the organization has no parent, and users of the parent workspace applications aren't routed to it at sign-in.
metadataobjectNoBusiness attribute values in metadata.payload. The values must match the organization schema.
authentication_mechanismsarray of stringsNoAllowed sign-in methods, such as password or webauthn. Overrides the template value.
tip

The API accepts a request without template_id and parent_id, but it doesn't apply the Default organization template or Default organization parent tenant settings. Pass both in every request.

Example requests​

Minimal request (with template and parent)

{
  "id": "acme-corp-001",
  "name": "ACME Corporation",
  "template_id": "a13ee0f6236f4d7f89085945c3f75cd1",
  "parent_id": "{workspace-id}"
}

Recommended request (with template and business attributes)

{
  "id": "acme-corp-001",
  "name": "ACME Corporation",
  "template_id": "a13ee0f6236f4d7f89085945c3f75cd1",
  "parent_id": "{workspace-id}",
  "description": "ACME Corporation - Global Manufacturing",
  "domains": ["acme.com"],
  "metadata": {
    "payload": {
      "salesforceId": "001xx000003DGb2AAG",
      "orgEntitlements": ["premium", "analytics", "api-access"],
      "region": "North America"
    }
  }
}

cURL example

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

Success response (201 Created)

{
  "id": "acme-corp-001",
  "name": "ACME Corporation",
  "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}.connect.secureauth.com/{tenant-id}/acme-corp-001",
  "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 > Organizations.
  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.

Step 4: Invite the organization administrator​

A new organization has no administrators, even when it's created from a template. Invite the first administrator from the partner side and give them the Organization Admin (manager) role. They then manage their own users in the delegated admin portal.

See Add the first organization administrator for the admin console steps and the API calls.

See also​