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.
Field | Value | Req/Default | Notes |
---|---|---|---|
id |
id | Auto-generated | Org’s ID. Always starts with “org_”. Example: |
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. |
See Custom attributes under Users for details.
Method | Permissions |
---|---|
List, Get | read |
Create, Update, Delete | write |
List all organizations in the current realm.
Param | Value | Default | |
---|---|---|---|
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 |
GET /v1/orgs
$res = $client->orgs()->all();
AuthRocket::Org.all realm_id: 'rl_0v1zTHXhtNgmDaXaDYSAqx'
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
}
]
Retrieve a specific organization.
Param | Value | Default | |
---|---|---|---|
expand |
memberships |
Include membership and user details in the response |
GET /v1/orgs/:org_id
$res = $client->orgs()->find('org_0v1zWRHJVm7JY8vUqDRuyx');
AuthRocket::Org.find 'org_0v1zWRHJVm7JY8vUqDRuyx'
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 a new organization.
Param | Value | Default | |
---|---|---|---|
user_ids |
user_ids | One, or an array of, user_ids used to auto-build memberships for the new org. | |
user |
object | A valid |
|
permissions |
string | One, or an array of, permissions to use for all memberships created via |
Extra parameters are all optional. user
should be a standard hash when using the Ruby bindings.
POST /v1/orgs
{ "org" :
{ "name" : "Widgets Inc"
}
}
$res = $client->orgs()->create([
"name" => "Widgets Inc"
]);
org = AuthRocket::Org.create(
name: 'Widgets Inc'
)
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"]
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’s attributes. Only provided attributes are changed.
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.'
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"]
Triggers an org.updated
event.
Deletes an org.
DELETE /v1/orgs/:org_id
$res = $client->orgs()->delete('org_0v1zWRHJVm7JY8vUqDRuyx');
org=AuthRocket::Org.find 'org_0v1zWRHJVm7JY8vUqDRuyx'
org.delete
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.
Triggers an org.deleted
event and zero or more membership.deleted
events
Questions? Find a Typo? Get in touch.