Orgs

Orgs can be thought of as an Account or Organization. Orgs are associated to Users via Memberships.

While it is possible to create just Users without corresponding Orgs and Memberships, LoginRocket always creates Orgs and Memberships, even in single-user (non-team) mode. This is because LoginRocket treats Users as a login ‘identity’ and Orgs as the actual account.

Often it is desirable to maintain an org/account history even when it is to be “deleted”. Org supports setting state = closed for this purpose. closed is a final, permanent state.

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Org’s ID. Always starts with “org_”. Example: org_USkZSudITtpKPqQcyxU84
state active, inactive, closed 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.

Required 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 /v2/orgs

var resp = await authrocket.orgs.all()
$res = $authrocket->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
    }
  ]
}

console.log(resp.results)
[ { 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 /v2/orgs/:org_id

var resp = await authrocket.orgs.find('org_0v1zWRHJVm7JY8vUqDRuyx')
$res = $authrocket->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
}

console.log(resp.results)
{ 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 simple hash/dict/json object.

Request

Example
POST /v2/orgs

{ "org" :
  { "name" : "Widgets Inc"
  }
}

var resp = await authrocket.orgs.create({
  name: "Widgets Inc"
})
$res = $authrocket->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:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["Name can't be blank"]

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 /v2/orgs/:org_id

{ "org" :
  { "name" : "Widgets, Inc."
  }
}

var resp = await authrocket.orgs.update('org_0v1zWRHJVm7JY8vUqDRuyx', {
  name: "Widgets, Inc."
})
$res = $authrocket->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:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["Name can't be blank"]

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.

Close or delete an org

By default, closes an org, maintaining associated account history.

To delete the org and all associated account history, add ?force=true.

Request

Example
DELETE /v2/orgs/:org_id
DELETE /v2/orgs/:org_id?force=true

var resp = await authrocket.orgs.delete('org_0v1zWRHJVm7JY8vUqDRuyx', {force: false})
$res = $authrocket->orgs->delete('org_0v1zWRHJVm7JY8vUqDRuyx', {'force'=>false});
org=AuthRocket::Org.find 'org_0v1zWRHJVm7JY8vUqDRuyx'
org.delete(force: false)

Response

Example

On close, Status: 200, with same body as Get an Org.
On delete, Status: 202.

On success, returns an object with no errors.

On failure, returns an object with errors.

resp.hasErrors()
// => true

On success, returns an object with no errors.

On failure, returns an object with errors.

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

On success, returns original object.

On failure, returns false.

Events

On close, triggers an org.updated event.
On delete, triggers an org.deleted event and zero or more membership.deleted events.

Contents
Fields Required permissions List orgs Get an org Create an org Update an org Close or delete an org