Organization

See all management resources

An organization represents the highest level of the App Services data hierarchy. It contains applications (and the entities and collections they contain) and is associated with one or more administrators. An organization can be representative of a company, team, or project. It allows multiple applications  to be shared within the organization with other administrators.

Using the App services API, you can create an organization through a form post and get an organization by UUID or name. In addition, you can activate or reactivate an organization, generate and retrieve an organization's client credentials, and get an organization's activity feed. You can also create an organization application through a form post, generate and retrieve credentials for the application, and delete the application. You can also get the applications in an organization. Additionally, you can add an admin user to an organization, get the admin users in an organization, and remove an admin user from an organization.

Creating an organization

Use the POST method to create an organization through a form post.

Request URI

POST /organizations|orgs {request body}

Parameters

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X -i POST "https://api.usergrid.com/management/orgs" -d '{"password":"test12345","email":"tester123@hotmail.com","name":"test","username":"test123","organization":"testorg"}'

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
management.create_organization 'testorg', 'test123', 'test', 'tester123@hotmail.com', 'test12345'

var options = {
    method:'POST',
    endpoint:'management/orgs',
    body:{ 
          password:'test12345', 
          email:'tester12345@gmail.com', 
          name:'test', 
          username:'tes123', 
          organization:'testorg' 
    }    
};
client.request(options, function (err, data) {
    if (err) {
        //error — POST failed
    } else {
        //success — data will contain raw results from API call        
    }
});

Example - Response

{
  "action": "new organization",
  "status": "ok",
  "data":  {
    "owner":  {
      "applicationId": "00000000-0000-0000-0000-000000000001",
      "username": "tester123",
      "name": "test",
      "email": "tester123@hotmail.com",
      "activated": false,
      "disabled": false,
      "uuid": "48c92c73-0d7e-11e2-98b9-12313d288ee0",
      "adminUser": true,
      "displayEmailAddress": "tester123 <tester123@hotmail.com>",
      "htmldisplayEmailAddress": "tester123 <<a href="mailto:tester123@hotmail.com">tester123@hotmail.com</a>>"
    },
    "organization":  {
      "name": "testorg",
      "uuid": "5de0bb69-0d7f-11e2-87b9-12313d288ff0"
    }
  },
  "timestamp": 1349284674173,
  "duration": 21376
}

Getting an organization

Use the GET method to retrieve an organization given a specified UUID or username.

Request URI

GET /organizations|orgs/{org_name}|{uuid}

Parameters

Note: You also need to provide a valid access token with the API call. See Authentication and access in App Services for details.

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X GET "https://api.usergrid.com/management/orgs/testorg"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
org = mgmt.organization 'testorg'

var options = {
    method:'GET',
    endpoint:'management/orgs/testorg'
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call        
    }
});

Example - Response

{
  "timestamp": 1349286861746,
  "duration": 18,
  "organization":  {
    "users":  {
      "tester123":  {
        "applicationId": "00000000-0000-0000-0000-000000000001",
        "username": "tester123",
        "name": "test",
        "email": "tester123@hotmail.com",
        "activated": true,
        "disabled": false,
        "uuid": "327b527f-cd0c-11e1-bcf7-12313d1c4491",
        "adminUser": true,
        "displayEmailAddress": "tester123 <tester123@hotmail.com>",
        "htmldisplayEmailAddress": "tester123 <<a href="mailto:tester123@hotmail.com">tester123@hotmail.com</a>>"
      }
    },
    "name": "testorg",
    "applications":  {
      "tester123/sandbox": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
      "tester123/testapp1": "be08a5f9-fdd3-11e1-beca-12313d027471",
      "tester123/testapp2": "cede5b7e-fe90-11e1-95c8-12313b122c56"
    },
    "uuid": "33dd0563-cd0c-11e1-bcf7-12313d1c4491"

Activating an organization

Use the GET method to activate an organization from a link provided in an email notification.

Request URL

GET /organizations|orgs/{org_name}|{uuid}/activate?token={token}&confirm={confirm_email}

Parameters

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X GET "https://api.usergrid.com/management/orgs/testorg/activate?token=33dd0563-cd0c-11e1-bcf7-12313d1c4491"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mgmt['orgs/testorg/activate'].get params: { token: '33dd0563-cd0c-11e1-bcf7-12313d1c4491' }

var options = {
    method:'GET',
    endpoint:'management/orgs/testorg/activate',
    qs:{token:'33dd0563-cd0c-11e1-bcf7-12313d1c4491'}
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "activate organization",
  "timestamp": 1337928462810,              
  "duration": 3342
}

Reactivating an organization

Use the GET method to reactivate an organization.

Request URI

GET /organizations|orgs/{org_name}|{uuid}/reactivate

Parameters

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X GET "https://api.usergrid.com/management/orgs/testorg/reactivate"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mgmt['orgs/testorg/reactivate']

var options = {
    method:'GET',
    endpoint:'management/orgs/testorg/reactivate'
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "reactivate organization",
  "timestamp": 1349385280891,
  "duration": 3612
}

Generating organization client credentials

Use the POST method to generate new credentials for an organization client.

Request URI

POST /organizations|orgs/{org_name}|{uuid}/credentials

Parameters

Note: You also need to provide a valid access token with the API call. See Authentication and access in App Services for details.

Example - Request

• cURL
• JavaScript
• Ruby
• Node.js

curl -X POST "https://api.usergrid.com/management/orgs/credentials"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mgmt['orgs/credentials'].create

var options = {
    method:'POST',
    endpoint:'management/orgs/credentials'
};
client.request(options, function (err, data) {
    if (err) {
        //error — POST failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "generate organization client credentials",
  "timestamp": 1349385795647,
  "duration": 7,
  "credentials":  {
    "client_id": "c2V7N61DY90MCdG78xIxPRxFdQ",                  
    "client_secret": "c2V7WEdXIutZWEkWdySLCt_lYDFVMMN"                      
  }
}

Retrieving organization client credentials

Use the GET method to retrieve the credentials for an organization client.

Request URL

GET /organizations|orgs/{org_name}|{uuid}/credentials

Parameters

Note: You also need to provide a valid access token with the API call. See Authentication and access in App Services for details.

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X GET "https://api.usergrid.com/management/orgs/testorg/credentials"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mgmt['orgs/testorg/credentials']

var options = {
    method:'GET',
    endpoint:'management/orgs/testorg/credentials'
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "get organization client credentials",
  "timestamp": 1349386672984,
  "duration": 690,
  "credentials":  {
    "client_id": "c2V7N61DY90MCdG78xIxPRxFdQ",                  
    "client_secret": "c2V7WEdXIutZWEkWdySLCt_lYDFVMMN"                      
  }
}

Getting an organization's activity feed

Use the GET method to get an organization's activity feed.

Request URI

GET /organizations|orgs/{org_name}|{uuid}/feed

Parameters

Note: You also need to provide a valid access token with the API call. See Authentication and access in App Services for details.

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X GET "https://api.usergrid.com/management/orgs/testorg/feed"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
activities = mgmt['orgs/testorg/feed'].collection

var options = {
    method:'GET',
    endpoint:'management/orgs/testorg/feed'
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
 {
  "action": "get organization feed",
  "status": "ok",
  "entities":  [
     {
      "uuid": "cf4d981c-fe90-11e1-95c8-12313b122c56",
      "type": "activity",
      "created": 1347643370454,
      "modified": 1347643370454,
      "actor":  {
        "displayName": "tester123",
        "objectType": "person",
        "uuid": "327b527f-cd0c-11e1-bcf7-12313d1c4491",
        "entityType": "user"
      },
      "category": "admin",
      "metadata":  {
        "cursor": "gGkAAQMAgGkABgE5xc3r1gCAdQAQz02YHP6QEeGVyBIxOxIsVgCAdQAQz3SoH_6QEeGVyBIxOxIsVgA",
        "path": "/groups/33dd0563-cd0c-11e1-bcf7-12313d1c4491/feed/cf4d981c-fe90-11e1-95c8-12313b122c56"
      },
"object":  {
        "displayName": "testapp2",
        "objectType": "Application",
        "uuid": "cede5b7e-fe90-11e1-95c8-12313b122c56",
        "entityType": "application_info"
      },
      "published": 1347643370454,
      "title": "<a mailto="mailto:tester123@hotmail.com">tester123 (tester123@hotmail.com)</a> created a new application named testapp2",
      "verb": "create"
    },...
,
  "timestamp": 1349387253811,

Creating an organization application

Use the POST method to create an application for an organization through a form post.

Request URI

POST /organizations|orgs/{org_name}|{org_uuid}/apps {request body}

Parameters

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X -i POST "https://api.usergrid.com/management/orgs/testorg/apps" -d '{"access_token":"YWMtmNIFFBI6EeKvXSIACowF7QAAATpL0bVQtGOWe8PMwLfQ9kD_VKQa7IH4UBQ","name":"testapp1"}'

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mynewapp = mgmt['orgs/testorg/apps'].create name: 'testapp1', access_token: 'YWMtmNIFFBI6EeKvXSIACowF7QAAATpL0bVQtGOWe8PMwLfQ9kD_VKQa7IH4UBQ'

var options = {
    method:'POST',
    endpoint:'management/orgs/testorg/apps',
    body:{ 
          access_token:'YWMtmNIFFBI6EeKvXSIACowF7QAAATpL0bVQtGOWe8PMwLfQ9kD_VKQa7IH4UBQ', 
          name:'testapp1' 
    }    
};
client.request(options, function (err, data) {
    if (err) {
        //error — POST failed
    } else {
        //success — data will contain raw results from API call        
    }
});

Example - Response

{
  "action": "new application for organization",
  "timestamp": 1338914698135,
  "duration": 701
}

Deleting an organization application

Use the DELETE method to delete an application from an organization.

Request URI

DELETE /organizations|orgs/{org_name}|{org_uuid}/apps/{app_name}|{app_uuid}

Parameters

Note: You also need to provide a valid access token with the API call. See Authentication and access in App Services for details.

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X DELETE "https://api.usergrid.com/management/orgs/testorg/apps/testapp1"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mgmt['orgs/testorg/apps/testapp1'].delete

var options = {
    method:'DELETE',
    endpoint:'management/orgs/testorg/apps/testapp1'
};
client.request(options, function (err, data) {
    if (err) {
        //error — DELETE failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "delete application from organization",
  "timestamp": 1349817715666,
  "duration": 0
}

Generating application credentials

Use the POST method to generate the client ID and client secret credentials for an application in an organization.

Request URI

POST /organizations|orgs/{org_name}|{uuid}/applications|apps/{app_name}|{uuid}/credentials

Parameters

Note: You also need to provide a valid access token with the API call. See Authentication and access in App Services for details.

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X POST "https://api.usergrid.com/management/orgs/testorg/apps/testapp1/credentials"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mgmt['orgs/testorg/apps/testapp1/credentials'].create

var options = {
    method:'POST',
    endpoint:'management/orgs/testorg/apps/testapp1/credentials'
};
client.request(options, function (err, data) {
    if (err) {
        //error — POST failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "generate application client credentials",
  "timestamp": 1349815979529,
  "duration": 535,
  "credentials":  {
    "client_id": "YXA7ygil-f3TEeG-yhIxPQK1cQ",
    "client_secret": "YXA65gYlqja8aYYSAy8Ox3Vg5aRZp48"
  }
}

Getting application credentials

Use the GET method to retrieve the client ID and client secret credentials for an application in an organization.

Request URI

GET /organizations|orgs/{org_name}|{uuid}/applications|apps/{app_name}|{uuid}/credentials

Parameters

Note: You also need to provide a valid access token with the API call. See Authentication and access in App Services for details.

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X GET "https://api.usergrid.com/management/orgs/testorg/apps/testapp1/credentials"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mgmt['orgs/testorg/apps/testapp1/credentials']

var options = {
    method:'GET',
    endpoint:'management/orgs/testorg/apps/testapp1/credentials'
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "get application client credentials",
  "timestamp": 1349816819545,
  "duration": 7,
  "credentials":  {
    "client_id": "YXA7ygil-f3TEeG-yhIxPQK1cQ",
    "client_secret": "YXA65gYlqja8aYYSAy8Ox3Vg5aRZp48"
  }
}

Getting the applications in an organization

Use the GET method to retrieve the applications in an organization.

Request URI

GET /organizations|orgs/{org_name}|{uuid}/applications|apps

Parameters

Note: You also need to provide a valid access token with the API call. See Authentication and access in App Services for details.

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X GET "https://api.usergrid.com/management/orgs/testorg/apps"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
apps = mgmt['orgs/testorg/apps'].collection

var options = {
    method:'GET',
    endpoint:'management/orgs/testorg/apps'
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "get organization application",
  "data":  {
    "testorg/sandbox": "3500ba10-cd0c-11e1-bcf8-12313d1c5591",
    "testorg/testapp1": "be09a5f9-fdd3-11e1-beca-12313d027361",
    "testorg/testapp2": "cede5b8e-fe90-11e1-65c8-12313b111c56"    
  },
  "timestamp": 1349815338635,
  "duration": 22
}

Adding an admin user to an organization

Use the PUT method to add an existing admin user to an organization.

Request URI

PUT /organizations|orgs/{org_name}|{org_uuid}/users/{username|email|uuid}

Parameters

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X PUT "https://api.usergrid.com/management/orgs/testorg/users/test123"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mgmt['orgs/testorg/users/test123'].put nil

var options = {
    method:'PUT',
    endpoint:'management/orgs/testorg/users/test123'
};
client.request(options, function (err, data) {
    if (err) {
        //error — PUT failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "add user to organization",
  "status": "ok",
  "data":  {
    "user":  {
      "applicationId": "00000000-0000-0000-0000-000000000001",
      "username": "tester123",
      "name": "test",
      "email": "tester123@hotmail.com",
      "activated": true,
      "disabled": false,
      "uuid": "335b527f-cd0d-11e1-bef8-12331d1c5591",
      "adminUser": true,
      "displayEmailAddress": "tester123 <tester123@hotmail.com>",
      "htmldisplayEmailAddress": "tester123 <<a href="mailto:tester123@hotmail.com">tester123@hotmail.com</a>>"
    }
  },
  "timestamp": 1349390189106,
  "duration": 11808
}

Getting the admin users in an organization

Use the GET method to retrieve details about the admin users in an organization.

Request URI

GET /organizations|orgs/{org_name}|{org_uuid}/users

Parameters

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X GET "https://api.usergrid.com/management/orgs/testorg/users"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
admins = mgmt['orgs/testorg/users']

var options = {
    method:'GET',
    endpoint:'management/orgs/testorg/users'
};
client.request(options, function (err, data) {
    if (err) {
        //error — GET failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "get organization users",
  "data":  {
    "user":  {
      "applicationId": "00000000-0000-0000-0000-000000000001",
      "username": "tester123",
      "name": "test",
      "email": "tester123@hotmail.com",
      "activated": true,
      "disabled": false,
      "uuid": "335b527f-cd0d-11e1-bef8-12331d1c5591",
      "adminUser": true,
      "displayEmailAddress": "tester123 <tester123@hotmail.com>",
      "htmldisplayEmailAddress": "tester123 <<a href="mailto:tester123@hotmail.com">tester123@hotmail.com</a>>"
    }
  },
  "timestamp": 13494542201685,
  "duration": 10
}

Removing an admin user from an organization

Use the DELETE method to remove an admin user from an organization.

Request URI

DELETE /organizations|orgs/{org_name}|{org_uuid}/users/{username|email|uuid}

Parameters

Example - Request

• cURL
• JavaScript (HTML5)
• Ruby
• Node.js

curl -X DELETE "https://api.usergrid.com/management/orgs/testorg/users/test123"

mgmt = Usergrid::Management.new 'https://api.usergrid.com/'
mgmt['orgs/testorg/users/test123'].delete

var options = {
    method:'DELETE',
    endpoint:'management/orgs/testorg/users/test123'
};
client.request(options, function (err, data) {
    if (err) {
        //error — DELETE failed
    } else {
        //success — data will contain raw results from API call       
    }
});

Example - Response

{
  "action": "remove user from organization",
  "status": "ok",
  "data":  {
    "user":  {
      "applicationId": "00000000-0000-0000-0000-000000000001",
      "username": "tester123",
      "name": "test",
      "email": "tester123@hotmail.com",
      "activated": true,
      "disabled": false,
      "uuid": "335b527f-cd0d-11e1-bef8-12331d1c5591",
      "adminUser": true,
      "displayEmailAddress": "tester123 <tester123@hotmail.com>",
      "htmldisplayEmailAddress": "tester123 <<a href="mailto:tester123@hotmail.com">tester123@hotmail.com</a>>"
    }
  },
  "timestamp": 1349453590005,
  "duration": 727
}