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 the org 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_0v1zWRHJVm7JY8vUqDRuyx
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_sample123456'

Response

Example

Status: 200

{
  "collection": [
    {
      "created_at": 1672531200.0,
      "id": "org_sample123456",
      "name": "Widgets Inc",
      "object": "org",
      "realm_id": "rl_sample123456",
      "reference": null,
      "state": "active"
    }
  ],
  "more_results": false
}

// console.log(resp.results)
[
  {
    created_at: 1672531200.0,
    id: "org_sample123456",
    name: "Widgets Inc",
    object: "org",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active"
  }
]
// var_dump($res->results);
array(1) {
  [0]=> 
    array(7) {
      ["created_at"]=> float(1672531200.0)
      ["id"]=> string(16) "org_sample123456"
      ["name"]=> string(11) "Widgets Inc"
      ["object"]=> string(3) "org"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
    }
}
[AuthRocket::Org(
  created_at: 2023-01-01 00:00:00 UTC,
  id: "org_sample123456",
  name: "Widgets Inc",
  realm_id: "rl_sample123456",
  reference: nil,
  state: "active"
 )
]

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_sample123456

var resp = await authrocket.orgs.find('org_sample123456')
$res = $authrocket->orgs->find('org_sample123456');
org = AuthRocket::Org.find 'org_sample123456'

Response

Example

Status: 200

{
  "created_at": 1672531200.0,
  "custom": {},
  "id": "org_sample123456",
  "name": "Widgets Inc",
  "object": "org",
  "realm_id": "rl_sample123456",
  "reference": null,
  "state": "active"
}

// console.log(resp.results)
{
  created_at: 1672531200.0,
  custom: {},
  id: "org_sample123456",
  name: "Widgets Inc",
  object: "org",
  realm_id: "rl_sample123456",
  reference: null,
  state: "active"
}
// var_dump($res->fields);
array(8) {
  ["created_at"]=> float(1672531200.0)
  ["custom"]=> array(0) {}
  ["id"]=> string(16) "org_sample123456"
  ["name"]=> string(11) "Widgets Inc"
  ["object"]=> string(3) "org"
  ["realm_id"]=> string(15) "rl_sample123456"
  ["reference"]=> NULL
  ["state"]=> string(6) "active"
}
AuthRocket::Org(
 created_at: 2023-01-01 00:00:00 UTC,
 custom: {},
 id: "org_sample123456",
 name: "Widgets Inc",
 realm_id: "rl_sample123456",
 reference: nil,
 state: "active"
)

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

On success, status 201 with the new Org.

{
  "created_at": 1672531200.0,
  "custom": {},
  "id": "org_sample123456",
  "memberships": [],
  "name": "Widgets Inc",
  "new_record": true,
  "object": "org",
  "realm_id": "rl_sample123456",
  "reference": null,
  "state": "active"
}

On failure, status 422 with a standard error response.

On success, returns an object with the new Org.

// console.log(resp.results)
{
  created_at: 1672531200.0,
  custom: {},
  id: "org_sample123456",
  memberships: [],
  name: "Widgets Inc",
  new_record: true,
  object: "org",
  realm_id: "rl_sample123456",
  reference: null,
  state: "active"
}

On failure, returns an object with a standard error response.

On success, returns an object with the new Org.

// var_dump($res->fields);
array(10) {
  ["created_at"]=> float(1672531200.0)
  ["custom"]=> array(0) {}
  ["id"]=> string(16) "org_sample123456"
  ["memberships"]=> array(0) {}
  ["name"]=> string(11) "Widgets Inc"
  ["new_record"]=> bool(true)
  ["object"]=> string(3) "org"
  ["realm_id"]=> string(15) "rl_sample123456"
  ["reference"]=> NULL
  ["state"]=> string(6) "active"
}

On failure, returns an object with a standard error response.

On success, returns an object with the new Org.

AuthRocket::Org(
 created_at: 2023-01-01 00:00:00 UTC,
 custom: {},
 id: "org_sample123456",
 memberships: [],
 name: "Widgets Inc",
 new_record: true,
 realm_id: "rl_sample123456",
 reference: nil,
 state: "active"
)

On failure, returns an object with a standard error response.

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_sample123456

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

var resp = await authrocket.orgs.update('org_sample123456', {
  name: "Widgets, Inc"
})
$res = $authrocket->orgs->update('org_sample123456', [
  "name" => "Widgets, Inc"
]);
org = AuthRocket::Org.find 'org_sample123456'
org.update name: 'Widgets, Inc'

Response

Example

On success, status 200 with the updated Org.

{
  "created_at": 1672531200.0,
  "custom": {},
  "id": "org_sample123456",
  "name": "Widgets Inc",
  "object": "org",
  "realm_id": "rl_sample123456",
  "reference": null,
  "state": "active"
}

On failure, status 422 with a standard error response.

On success, returns an object with the updated Org.

// console.log(resp.results)
{
  created_at: 1672531200.0,
  custom: {},
  id: "org_sample123456",
  name: "Widgets Inc",
  object: "org",
  realm_id: "rl_sample123456",
  reference: null,
  state: "active"
}

On failure, returns an object with a standard error response.

On success, returns an object with the updated Org.

// var_dump($res->fields);
array(8) {
  ["created_at"]=> float(1672531200.0)
  ["custom"]=> array(0) {}
  ["id"]=> string(16) "org_sample123456"
  ["name"]=> string(11) "Widgets Inc"
  ["object"]=> string(3) "org"
  ["realm_id"]=> string(15) "rl_sample123456"
  ["reference"]=> NULL
  ["state"]=> string(6) "active"
}

On failure, returns an object with a standard error response.

On success, returns the updated Org object.

AuthRocket::Org(
 created_at: 2023-01-01 00:00:00 UTC,
 custom: {},
 id: "org_sample123456",
 name: "Widgets Inc",
 realm_id: "rl_sample123456",
 reference: nil,
 state: "active"
)

On failure, returns false and updates object with standard errors.

Events

Triggers an org.updated event.

Close or delete an org

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

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

Request

Example
DELETE /v2/orgs/org_sample123456
DELETE /v2/orgs/org_sample123456?force=true

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

Response

Example

On close, status 200 with the updated Org.

{
  "created_at": 1672531200.0,
  "custom": {},
  "id": "org_sample123456",
  "name": "Widgets Inc",
  "object": "org",
  "realm_id": "rl_sample123456",
  "reference": null,
  "state": "closed"
}

On delete, status 202.
On failure, status 422 with a standard error response.

On close, returns an object with the updated Org.

// console.log(resp.results)
{
  created_at: 1672531200.0,
  custom: {},
  id: "org_sample123456",
  name: "Widgets Inc",
  object: "org",
  realm_id: "rl_sample123456",
  reference: null,
  state: "closed"
}

On delete, returns an object with no errors.
On failure, returns an object with a standard error response.

On close, returns an object with the updated Org.

// var_dump($res->fields);
array(8) {
  ["created_at"]=> float(1672531200.0)
  ["custom"]=> array(0) {}
  ["id"]=> string(16) "org_sample123456"
  ["name"]=> string(11) "Widgets Inc"
  ["object"]=> string(3) "org"
  ["realm_id"]=> string(15) "rl_sample123456"
  ["reference"]=> NULL
  ["state"]=> string(6) "closed"
}

On delete, returns an object with no errors.
On failure, returns an object with a standard error response.

On close, returns the updated Org object.

AuthRocket::Org(
 created_at: 2023-01-01 00:00:00 UTC,
 custom: {},
 id: "org_sample123456",
 name: "Widgets Inc",
 realm_id: "rl_sample123456",
 reference: nil,
 state: "closed"
)

On delete, returns the original object.
On failure, returns false and updates object with standard errors.

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