Orgs

Orgs are a container. They can represent an Account, an Organization, a Subscription, or just about anything else. For simple apps, you may not need Orgs at all–just stick with Users.

For any app where you may need more than one User to be associated with an Account, Organization, Subscription, or whatever, then use an Org.

Orgs are associated to Users via Memberships.

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Org’s ID. Always starts with “org_”. Example: org_USkZSudITtpKPqQcyxU84

state active,
inactive
active
name string Required Name/title of the Org.
realm_id realm_id Required ID of Realm this Org belongs to.
reference string Optional Field to map to your app's own ID.
custom hash Optional Hash of custom attributes.
request hash

Hash of request attributes to add to Event. See notes.

Custom attributes

See Custom attributes under Users for details.

Permissions

MethodPermissions
List, Get read
Create, Update, Delete write

List orgs

List all organizations in the current realm.

Parameters

ParamValueDefault
reference reference Filter by reference; must be an exact match
state state Filter by state
after org_id ID of the last org you've seen
max_results integer 100 Range: 1-1000
sort id,
name
name
direction asc,
desc
asc
expand custom

Include custom in the response

Request

Example
GET /v1/orgs
$res = $client->orgs()->all();
AuthRocket::Org.all realm_id: 'rl_0v1zTHXhtNgmDaXaDYSAqx'

Response

Example

Status: 200

{ "more_results" : false,
  "collection" : [
    { "id" : "org_0v1zWRHJVm7JY8vUqDRuyx",
      "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
      "name" : "Widgets Inc",
      "state" : "active",
      "reference" : null,
      "object" : "org",
      "created_at" : 1396582483.874
    }
  ]
}
var_dump($res->results);
  array(1) {
    [0]=>
    array(7) {
      ["id"]=> string(26) "org_0v1zWRHJVm7JY8vUqDRuyx"
      ["realm_id"]=> string(25) "rl_0v1zTHXhtNgmDaXaDYSAqx"
      ["name"]=> string(8) "Widgets Inc"
      ["state"]=> string(6) "active"
      ["reference"]=> NULL
      ["object"]=> string(3) "org"
      ["created_at"]=> float(1396582483.874)
    }
  }
[#<AuthRocket::Org:0x3fc2197af5ec>
  id: "org_0v1zWRHJVm7JY8vUqDRuyx",
  attribs: {
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "name"=>"Widgets Inc",
    "state"=>"active",
    "reference"=>nil,
    "object"=>"org",
    "created_at"=>1396582483.874
  },
  metadata: {
    "more_results"=>false
  }
]

Get an org

Retrieve a specific organization.

Parameters

ParamValueDefault
expand memberships Include membership and user details in the response

Request

Example
GET /v1/orgs/:org_id
$res = $client->orgs()->find('org_0v1zWRHJVm7JY8vUqDRuyx');
AuthRocket::Org.find 'org_0v1zWRHJVm7JY8vUqDRuyx'

Response

Example

Status: 200

{ "id" : "org_0v1zWRHJVm7JY8vUqDRuyx",
  "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
  "name" : "Widgets Inc",
  "state" : "active",
  "reference" : null,
  "custom" : {},
  "object" : "org",
  "created_at" : 1396582483.874
}
var_dump($res->fields);
  array(8) {
    ["id"]=> string(26) "org_0v1zWRHJVm7JY8vUqDRuyx"
    ["realm_id"]=> string(25) "rl_0v1zTHXhtNgmDaXaDYSAqx"
    ["name"]=> string(8) "Widgets Inc"
    ["state"]=> string(6) "active"
    ["reference"]=> NULL
    ["custom"]=> array(0) {}
    ["object"]=> string(3) "org"
    ["created_at"]=> float(1396582483.874)
  }
#<AuthRocket::Org:0x3fc2197af5ec>
  id: "org_0v1zWRHJVm7JY8vUqDRuyx",
  attribs: {
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "name"=>"Widgets Inc",
    "state"=>"active",
    "reference"=>nil,
    "custom"=>{},
    "object"=>"org",
    "created_at"=>1396582483.874
  }

Create an org

Create a new organization.

Parameters

ParamValueDefault
user_ids user_ids One, or an array of, user_ids used to auto-build memberships for the new org.
user object

A valid user json object (see Create a User) to create alongside this org. Will auto-build a membership between the two.

permissions string

One, or an array of, permissions to use for all memberships created via user_ids or user.

Extra parameters are all optional. user should be a standard hash when using the Ruby bindings.

Request

Example
POST /v1/orgs
{ "org" :
  { "name" : "Widgets Inc"
  }
}
$res = $client->orgs()->create([
  "name" => "Widgets Inc"
]);
org = AuthRocket::Org.create(
  name: 'Widgets Inc'
)

Response

Example

Status: 201, with same body as Get an Org.

On success, returns same object as Get an Org.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(19) "Name can't be blank"
  }

On success, returns same object as Get an Org.

On failure, returns an object without an id, but with errors:

# => #<AuthRocket::Org:0x3fde5fa18df8> id: nil, ...
org.errors?
# => true
org.valid?
# => false
org.errors
# => ["Name can't be blank"]

Events

Triggers an org.created event. If user is provided, triggers user.created. If user and/or user_ids provided, triggers one or more membership.created events.

Update an org

Update an org’s attributes. Only provided attributes are changed.

Request

Example
PUT /v1/orgs/:org_id
{ "org" :
  { "name" : "Widgets, Inc."
  }
}
$res = $client->orgs()->update('org_0v1zWRHJVm7JY8vUqDRuyx', [
  "name" => "Widgets, Inc."
]);
org=AuthRocket::Org.find 'org_0v1zWRHJVm7JY8vUqDRuyx'
org.save name: 'Widgets, Inc.'

Response

Example

Status: 200, with same body as Get an Org.

On success, returns same object as Get an Org.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(31) "Name can't be blank"
  }

On success, returns same object as Get an Org.

On failure, returns false:

# => false
org.errors
# => ["Name can't be blank"]

Events

Triggers an org.updated event.

Delete an org

Deletes an org.

Request

Example
DELETE /v1/orgs/:org_id
$res = $client->orgs()->delete('org_0v1zWRHJVm7JY8vUqDRuyx');
org=AuthRocket::Org.find 'org_0v1zWRHJVm7JY8vUqDRuyx'
org.delete

Response

Example

Status: 204

On success, returns an object with no errors.

On failure, returns an object with errors.

$res->hasErrors();
// => true or false

On success, returns original object.

On failure, returns false.

Events

Triggers an org.deleted event and zero or more membership.deleted events

Questions? Find a Typo? Get in touch.