Organizations API

Use the Organizations API to manage information about all the Apperian organizations on which the authenticated user can operate. This information includes an org_id for each organization. An org_id is the unique identifier that Apperian assigns to each organization.

If you manage any affiliated (child and grandchild) organizations, you can authenticate through the API as an administrator of a parent organization and send API requests to perform functions in any of the affiliated organizations without having to re-authenticate; this is done by including the org_id in the URL of the request. For more information, see Sending Requests for Affiliated (Child) Organizations.

Common Organization Data

In order to simplify the organization management process, the response from the following endpoints always returns an organization object in JSON form:

  • GET /v3/organizations/<org_id>
  • PUT /v3/organizations/<org_id>

For more information about fields within the common organization object, see Common Organization Data.

Resources

GET /v1/organizations/

List Organizations

Returns information about all the organizations on which the authenticated user can operate. If the authenticated user is an administrator (user with the “Administrator” role), the list includes the user’s organization, its parent organization (if there is one) and any affiliated (child and grandchild) organizations. If the user is not an administrator, the list includes the user’s organization only.

The response identifies the org_id for each listed organization. If you are working in an Apperian organization that has affiliated organizations, you can include org_id in an API request to perform functions in any of your affiliated organizations without having to re-authenticate. For more information, see Sending Requests for Affiliated (Child) Organizations.

URLs

Environment URL
North America https://na01ws.apperian.com/v1/organizations/
Europe https://eu01ws.apperian.eu/v1/organizations/

URL Parameters

None

Header Parameters

X-TOKEN
(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.

Data Parameters

None

Example Request

The following cURL request returns information about the authenticated user’s organization, the parent organization, and the two affiliated organizations (sub_orgs).

curl -X GET https://eu01ws.apperian.eu/v1/organizations/ --header "X-TOKEN:OxS8iqSHSSmRqcqQ1pXXwg"

Example Response

{
  "parent_id": null,
  "name": "HoneyBee's Organic Honey",
  "id": "Aegm9Dfmsbb4dSxpt8lZTjA",
  "sub_orgs": [
    {
      "sub_orgs": [],
      "parent_id": "Aegm9Dfmsb34dSxpt8lZTjA",
      "name": "Honey From the West",
      "id": "XTBEV_SGPlI0oI8ozGTh0A"
    },
    {
      "sub_orgs": [],
      "parent_id": "Aegm9aDfmsb4dSxpt8lZTjA",
      "name": "Honey from the East",
      "id": "Vj9lkP0txgod4BMIyzMvxQ"
    }
  ]
}
GET /v3/organizations/(org_psk)/

List Data for a Specific Organization

Users will see fewer fields than Administrators.

Returns data about the specified organization.

URLs

Environment URL
North America https://na01ws.apperian.com/v3/organizations/<org_id>
Europe https://eu01ws.apperian.eu/v3/organizations/<org_id>

URL Parameters

org_id
(Required) Unique ID for the organization. DATA TYPE: string URL Parameters
org_id
(Required) Unique ID for the organization. DATA TYPE: string

Header Parameters

X-TOKEN
(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.

Example Request

curl -X GET https://na01ws.apperian.com/v3/organizations/4GeRjtGhiw6kx1jNx4QdNA
     --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"

If the request is successful, the response is an organization object in JSON form.

Example Response

{
    "organization": {
        "id":"4GeRjtGhiw6kx1jNx4QdNA",
        "parent_id":"a82BexNA0D82j5vZj4OW",
        "admin_branded":false,
        "app_installation_path":"Enterprise Apps",
        "apple_push_cert":true,
        "auth_type":0,
        "banner_image_enabled":false,
        "email_from_address":"apperian@arxan.com",
        "email_from_name":"The Apperian System",
        "email_reply_to_address":"apperian@arxan.com",
        "invite_subject_for_affiliated":"Apperian Affiliated Administrator",
        "invite_subject_for_user":"Welcome to Apperian",
        "invite_template_for_affiliated":"{...}",
        "invite_template_for_user":"Welcome to Apperian",
        "javascript_protection_policy_enabled":false,
        "kryptowire_enabled":false,
        "kryptowire_settings":null,
        "mandatory_update_notifications_enabled":false,
        "mocana_enabled": false,
        "name":"Arxan Technologies",
        "no_auth_app_delivery_enabled":true,
        "no_auth_policies_enabled":false,
        "policies_frequency_evaluation_in_hours":0,
        "remember_me_timeout_in_minutes":10080,
        "reviews_default_value":true,
        "reviews_enabled":true,
        "session_timeout_in_minutes":10,
        "support_email":"support@arxan.com",
        "vanity_subdomain":"arxan",
        "winphone_cert": false,
        "cors_domain_whitelist":[
            "http://arxan.com"
        ],
        "auth_settings":{
            "touch_id_auth":{
                "enable_touch_id":true
            }
        },
        "password_complexity":{
            "password_complexity_for_admins":{
                "account_lockout_threshold":0,
                "account_lockout_reset_timer_in_minutes":0,
                "account_lockout_permanent_lockout":false,
                "account_lockout_duration_in_minutes":0,
                "min_length":5,
                "min_lowercase":0,
                "min_number":0,
                "min_symbol":0,
                "min_uppercase":0,
                "password_expiration_in_minutes":0,
                "password_history":1,
                "password_reset_interval_time_in_minutes":0
            },
            "password_complexity_for_users":{
                "account_lockout_threshold":0,
                "account_lockout_reset_timer_in_minutes":0,
                "account_lockout_permanent_lockout":false,
                "account_lockout_duration_in_minutes":0,
                "min_length":5,
                "min_lowercase":0,
                "min_number":0,
                "min_symbol":0,
                "min_uppercase":0,
                "password_expiration_in_minutes":0,
                "password_history":1,
                "password_reset_interval_time_in_minutes":0
            }
        },
        "user_custom_metadata_template":{
            "cities_users":{
                "default":"1",
                "label":"Cities:",
                "options":[
                    {
                        "label":"Boston",
                        "value":"0"
                    },
                    {
                        "label":"London",
                        "value":"2"
                    },
                    {
                        "label":"Valladolid",
                        "value":"1"
                    }
                ],
                "type":"select"
            },
            "description":{
                "default":"default value",
                "label":"Description: ",
                "type":"textarea"
            },
            "enabled":{
                "default":true,
                "label":"Enabled by default? ",
                "type":"checkbox"
            },
            "name":{
                "default":"default value",
                "label":"Name: ",
                "type":"text"
            },
            "password":{
                "default":"default value",
                "label":"Password: ",
                "type":"password"
            },
            "restaurants":{
                "default":"0,2",
                "label":"Restaurants:",
                "options":[
                    {
                        "label":"Restaurant A",
                        "value":"0"
                    },
                    {
                        "label":"Restaurant B",
                        "value":"1"
                    },
                    {
                        "label":"Restaurant C",
                        "value":"2"
                    }
                ],
                "type":"multiselect"
            }
        },
        "application_custom_metadata_template":{
            "cities_applications":{
                "default":"1",
                "label":"Cities:",
                "options":[
                    {
                        "label":"Boston",
                        "value":"0"
                    },
                    {
                        "label":"London",
                        "value":"2"
                    },
                    {
                        "label":"Valladolid",
                        "value":"1"
                    }
                ],
                "type":"select"
            },
            "description":{
                "default":"default value",
                "label":"Description: ",
                "type":"textarea"
            },
            "enabled":{
                "default":true,
                "label":"Enabled by default? ",
                "type":"checkbox"
            },
            "name":{
                "default":"default value",
                "label":"Name: ",
                "type":"text"
            },
            "password":{
                "default":"default value",
                "label":"Password: ",
                "type":"password"
            },
            "restaurants":{
                "default":"0,2",
                "label":"Restaurants:",
                "options":[
                    {
                        "label":"Restaurant A",
                        "value":"0"
                    },
                    {
                        "label":"Restaurant B",
                        "value":"1"
                    },
                    {
                        "label":"Restaurant C",
                        "value":"2"
                    }
                ],
                "type":"multiselect"
            }
        }
    }
}
PUT /v3/organizations/(org_psk)/

Update an Organization’s Attributes

Authenticate as an Apperian administrator.

Update information about an organization. Not all fields are editable, however, if you submit an entire organization object, the service will accommodate the request as long as only editable fields are changed. See the list of editable fields below.

This endpoint returns the same organization object as GET /organizations/<id>, with a separate list of warnings if applicable. Refer to Common Organization Data for information about each field.

Additionally, you may use this endpoint to upload your APNS Push Certificate in order to enable push notifications for the iOS Catalog.

Editable Fields

  • support_email: String
  • email_from_name: String
  • email_from_address: String
  • email_reply_to_address: String
  • invite_template_for_user: String
  • invite_subject_for_user: String
  • invite_template_for_affiliated: String
  • invite_subject_for_affiliated: String
  • session_timeout_in_minutes: Integer
  • remember_me_timeout_in_minutes: Integer
  • no_auth_app_delivery_enabled: Boolean
  • password_complexity: Object
  • reviews_enabled: Boolean
  • application_custom_metadata_template: Object
  • user_custom_metadata_template: Object
  • banner_image_enabled: Boolean
  • no_auth_policies_enabled: Boolean
  • mandatory_update_notifications_enabled: Boolean
  • cors_domain_whitelist: List of Strings
  • reviews_default_value: Boolean
  • kryptowire_enabled: Boolean
  • kryptowire_settings: Object
  • admin_branded: Boolean
  • notify_on_device_registration: Boolean
  • policies_frequency_evaluation_in_hours: Integer

URLs

Environment URL
North America https://na01ws.apperian.com/v3/organizations/<org_id>
Europe https://eu01ws.apperian.eu/v3/organizations/<org_id>

URL Parameters

org_id
(Required) Unique ID for the organization. DATA TYPE: string

Header Parameters

X-TOKEN
(Required) API token or User token (POST /users/authenticate). For more information, see Authentication.
Files

This endpoint also accepts a multipart request with accompanying file(s), like POST /v1/applications/.

(Optional) push_cert_file Include this file when associating a new push certificate for the App Catalog in this organization. For more information, see Manage SSL Certificates.

Data Parameters
For an overview of accepted fields and how to use them, see Common Organization Data.

Example Request: Data Only

curl -X PUT https://na01ws.apperian.com/v3/organizations/4GeRjtGhiw6kx1jNx4QdNA
     --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"
     --header "Content-Type: application/json"
     --data '{"support_email": "support@my_company.com"}'

Example Request: Uploading an APNS Push Certificate

curl -X PUT https://na01ws.apperian.com/v3/organizations/4GeRjtGhiw6kx1jNx4QdNA
    --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"
    --header "Content-Type: multipart/form-data"
    -F 'push_cert_file=@MyPushCert.p12'
    -F 'data={"support_email": "support@my_company.com"}'

Example Request: Removing an APNS Push Certificate

curl -X PUT https://na01ws.apperian.com/v3/organizations/4GeRjtGhiw6kx1jNx4QdNA
    --header "X-TOKEN: eTg8ktZXRqKIBJTHunwP6A"
    --header "Content-Type: multipart/form-data"
    -F 'data={"apple_push_cert": false}'

If the request is successful, the response is an organization object in JSON form.

Example Response

{
    "warnings": [],
    "organization": {
        "id":"4GeRjtGhiw6kx1jNx4QdNA",
        "parent_id":"a82BexNA0D82j5vZj4OW",
        "admin_branded":false,
        "app_installation_path":"Enterprise Apps",
        "apple_push_cert":true,
        "auth_type":0,
        "banner_image_enabled":false,
        "email_from_address":"apperian@arxan.com",
        "email_from_name":"The Apperian System",
        "email_reply_to_address":"apperian@arxan.com",
        "invite_subject_for_affiliated":"Apperian Affiliated Administrator",
        "invite_subject_for_user":"Welcome to Apperian",
        "invite_template_for_affiliated":"{...}",
        "invite_template_for_user":"Welcome to Apperian",
        "javascript_protection_policy_enabled":false,
        "kryptowire_enabled":false,
        "kryptowire_settings":null,
        "mandatory_update_notifications_enabled":false,
        "mocana_enabled":false,,
        "name":"Arxan Technologies",
        "no_auth_app_delivery_enabled":true,
        "no_auth_policies_enabled":false,
        "policies_frequency_evaluation_in_hours":0,
        "remember_me_timeout_in_minutes":10080,
        "reviews_default_value":true,
        "reviews_enabled":true,
        "session_timeout_in_minutes":10,
        "support_email":"support@arxan.com",
        "vanity_subdomain":"arxan",
        "winphone_cert": false,
        "cors_domain_whitelist":[
            "http://arxan.com"
        ],
        "auth_settings":{
            "touch_id_auth":{
                "enable_touch_id":true
            }
        },
        "password_complexity":{
            "password_complexity_for_admins":{
                "account_lockout_threshold":0,
                "account_lockout_reset_timer_in_minutes":0,
                "account_lockout_permanent_lockout":false,
                "account_lockout_duration_in_minutes":0,
                "min_length":5,
                "min_lowercase":0,
                "min_number":0,
                "min_symbol":0,
                "min_uppercase":0,
                "password_expiration_in_minutes":0,
                "password_history":1,
                "password_reset_interval_time_in_minutes":0
            },
            "password_complexity_for_users":{
                "account_lockout_threshold":0,
                "account_lockout_reset_timer_in_minutes":0,
                "account_lockout_permanent_lockout":false,
                "account_lockout_duration_in_minutes":0,
                "min_length":5,
                "min_lowercase":0,
                "min_number":0,
                "min_symbol":0,
                "min_uppercase":0,
                "password_expiration_in_minutes":0,
                "password_history":1,
                "password_reset_interval_time_in_minutes":0
            }
        },
        "user_custom_metadata_template":{
            "cities_users":{
                "default":"1",
                "label":"Cities:",
                "options":[
                    {
                        "label":"Boston",
                        "value":"0"
                    },
                    {
                        "label":"London",
                        "value":"2"
                    },
                    {
                        "label":"Valladolid",
                        "value":"1"
                    }
                ],
                "type":"select"
            },
            "description":{
                "default":"default value",
                "label":"Description: ",
                "type":"textarea"
            },
            "enabled":{
                "default":true,
                "label":"Enabled by default? ",
                "type":"checkbox"
            },
            "name":{
                "default":"default value",
                "label":"Name: ",
                "type":"text"
            },
            "password":{
                "default":"default value",
                "label":"Password: ",
                "type":"password"
            },
            "restaurants":{
                "default":"0,2",
                "label":"Restaurants:",
                "options":[
                    {
                        "label":"Restaurant A",
                        "value":"0"
                    },
                    {
                        "label":"Restaurant B",
                        "value":"1"
                    },
                    {
                        "label":"Restaurant C",
                        "value":"2"
                    }
                ],
                "type":"multiselect"
            }
        },
        "application_custom_metadata_template":{
            "cities_applications":{
                "default":"1",
                "label":"Cities:",
                "options":[
                    {
                        "label":"Boston",
                        "value":"0"
                    },
                    {
                        "label":"London",
                        "value":"2"
                    },
                    {
                        "label":"Valladolid",
                        "value":"1"
                    }
                ],
                "type":"select"
            },
            "description":{
                "default":"default value",
                "label":"Description: ",
                "type":"textarea"
            },
            "enabled":{
                "default":true,
                "label":"Enabled by default? ",
                "type":"checkbox"
            },
            "name":{
                "default":"default value",
                "label":"Name: ",
                "type":"text"
            },
            "password":{
                "default":"default value",
                "label":"Password: ",
                "type":"password"
            },
            "restaurants":{
                "default":"0,2",
                "label":"Restaurants:",
                "options":[
                    {
                        "label":"Restaurant A",
                        "value":"0"
                    },
                    {
                        "label":"Restaurant B",
                        "value":"1"
                    },
                    {
                        "label":"Restaurant C",
                        "value":"2"
                    }
                ],
                "type":"multiselect"
            }
        }
    }
}