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/(organization)/¶ 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/<organization> Europe https://eu01ws.apperian.eu/v3/organizations/<organization> URL Parameters
- organization
- (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_settings":null, "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, "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/(organization)/¶ 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
- application_custom_metadata_template: Object
- user_custom_metadata_template: Object
- banner_image_enabled: Boolean
- no_auth_policies_enabled: Boolean
- cors_domain_whitelist: List of Strings
- reviews_default_value: Boolean
- kryptowire_settings: Object
- admin_branded: Boolean
- notify_on_device_registration: Boolean
- policies_frequency_evaluation_in_hours: Integer
- catalog_affiliated_org_access_enabled: Boolean
URLs
Environment URL North America https://na01ws.apperian.com/v3/organizations/<organization> Europe https://eu01ws.apperian.eu/v3/organizations/<organization> URL Parameters
- organization
- (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_fileInclude 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_settings":null, "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, "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" } } } }