Memberships

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Membership’s ID. Always starts with “mb_”. Example: mb_USl2uVyowwMB2FkI3EbCs
org_id org_id Required
user_id user_id Required
permissions string Optional One, or an array of, permission(s).
expires_at time_t Optional Time after which this membership will be automatically deleted.
request hash

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

org_id & user_id

One membership per user_id / org_id pair is allowed.

Permissions

Permissions are arbitrary tags that are meaningful to your application. In practice, in addition to permissions, these may also be names of roles, groups, or anything else meaningful to your application.

Each permission must match the regex /[a-z0-9*:;._-]/i. We recommend using : to delimit namespaces and * as a wildcard, eg: feature:admin, widget:*, or widget:12345. Each permission may be up to 62 characters. By default, accounts allow up to 20 permissions per membership.

Permissions beginning with ar: are reserved for use by AuthRocket itself. These permissions are currently used:

Required permissions

MethodPermissions
List, Get read
Create, Update, Delete write

List memberships for a user or an org

List all memberships associated with a specific user or org.

Parameters

ParamValueDefault
after membership_id ID of the last membership you've seen
max_results integer 100 Range: 1-1000
sort id id
direction asc, desc asc

Querying for an org_id will include the associated user records. Querying for a user_id will include the associated org records. Querying for both org_id and user_id will not include any associated records.

Request

Example
GET /v2/memberships?org_id=org_0v1zWRHJVm7JY8vUqDRuyx
GET /v2/memberships?user_id=usr_0v1zUpWdE4IiFc2w5ynShf

var resp = await authrocket.memberships.all({org_id: 'org_0v1zWRHJVm7JY8vUqDRuyx'})
var resp = await authrocket.memberships.all({user_id: 'usr_0v1zUpWdE4IiFc2w5ynShf'})
$res = $authrocket->memberships->all(['org_id' => 'org_0v1zWRHJVm7JY8vUqDRuyx']);
$res = $authrocket->memberships->all(['user_id' => 'usr_0v1zUpWdE4IiFc2w5ynShf']);
AuthRocket::Membership.all org_id: 'org_0v1zWRHJVm7JY8vUqDRuyx'
AuthRocket::Membership.all user_id: 'usr_0v1zUpWdE4IiFc2w5ynShf'

Response

Example

Status: 200

{ "more_results" : false,
  "collection" : [
    { "id" : "mb_0v1zWp1IEkl40q69WIQRaN",
      "permissions" : ["forum:admin"],
      "org_id" : "org_0v1zWRHJVm7JY8vUqDRuyx",
      "user_id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
      "object" : "membership",
      "expires_at" : null,
      "org" : {
        "id" : "org_0v1zWRHJVm7JY8vUqDRuyx",
        "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
        "name" : "Widgets Inc",
        "state" : "active",
        "reference" : null,
        "object" : "org"
      }
    }
  ]
}

console.log(resp.results)
[ { id: "mb_0v1zWp1IEkl40q69WIQRaN",
    permissions: ["forum:admin"],
    org_id: "org_0v1zWRHJVm7JY8vUqDRuyx",
    user_id: "usr_0v1zUpWdE4IiFc2w5ynShf",
    object: "membership",
    expires_at: null,
    org: {
      id: "org_0v1zWRHJVm7JY8vUqDRuyx",
      realm_id: "rl_0v1zTHXhtNgmDaXaDYSAqx",
      name: "Widgets Inc",
      state: "active",
      reference: null,
      object: "org"
    }
  }
]
var_dump($res->results);
  array(1) {
    [0]=>
    array(7) {
      ["id"]=> string(25) "mb_0v1zWp1IEkl40q69WIQRaN"
      ["permissions"]=> array(1) {
        [0]=> string(11) "forum:admin"
      }
      ["org_id"]=> string(26) "org_0v1zWRHJVm7JY8vUqDRuyx"
      ["org"]=> array(7) { ... }
      ["user_id"]=> string(26) "usr_0v1zUpWdE4IiFc2w5ynShf"
      ["object"]=> string(10) "membership"
      ["expires_at"]=> NULL
    }
  }
[#<AuthRocket::Membership:0x3fc218640acc>
  id: "mb_0v1zWp1IEkl40q69WIQRaN",
  attribs: {
    "permissions"=>["forum:admin"],
    "org_id"=>"org_0v1zWRHJVm7JY8vUqDRuyx",
    "org"=>#<AuthRocket::Org:0x3fc21aaf2a00>,
    "user_id"=>"usr_0v1zUpWdE4IiFc2w5ynShf",
    "object"=>"membership",
    "expires_at"=>nil,
  },
  metadata: {
    "more_results"=>false
  }
]

Get a membership

Retrieve a specific membership.

Request

Example
GET /v2/memberships/:membership_id

var resp = await authrocket.memberships.find('mb_0v1zWp1IEkl40q69WIQRaN')
$res = $authrocket->memberships->find('mb_0v1zWp1IEkl40q69WIQRaN');
membership = AuthRocket::Membership.find 'mb_0v1zWp1IEkl40q69WIQRaN'

Response

Example

Status: 200

{ "id" : "mb_0v1zWp1IEkl40q69WIQRaN",
  "permissions" : ["forum:admin"],
  "org_id" : "org_0v1zWRHJVm7JY8vUqDRuyx",
  "user_id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
  "object" : "membership",
  "expires_at" : null,
  "user" : {
    "id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
    "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
    "username" : "dave",
    "state" : "active",
    "reference" : null,
    "name" : "dave",
    "email" : "dave@example.com",
    "object" : "user",
    "last_login_at" : null,
    "created_at" : 1392447538.275,
    "first_name" : null,
    "last_name" : null,
    "custom" : {}
  },
  "org" : {
    "id" : "org_0v1zWRHJVm7JY8vUqDRuyx",
    "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
    "name" : "Widgets Inc",
    "state" : "active",
    "reference" : null,
    "object" : "org",
    "created_at" : 1397249256.259,
    "custom" : {}
  }
}

console.log(resp.results)
{ id: "mb_0v1zWp1IEkl40q69WIQRaN",
  permissions: ["forum:admin"],
  org_id: "org_0v1zWRHJVm7JY8vUqDRuyx",
  user_id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  object: "membership",
  expires_at: null,
  user: {
    id: "usr_0v1zUpWdE4IiFc2w5ynShf",
    realm_id: "rl_0v1zTHXhtNgmDaXaDYSAqx",
    username: "dave",
    state: "active",
    reference: null,
    name: "dave",
    email: "dave@example.com",
    object: "user",
    last_login_at: null,
    created_at: 1392447538.275,
    first_name: null,
    last_name: null,
    custom: {}
  },
  org: {
    id: "org_0v1zWRHJVm7JY8vUqDRuyx",
    realm_id: "rl_0v1zTHXhtNgmDaXaDYSAqx",
    name: "Widgets Inc",
    state: "active",
    reference: null,
    object: "org",
    created_at: 1397249256.259,
    custom: {}
  }
}
var_dump($res->fields);
  array(7) {
    ["id"]=> string(25) "mb_0v1zWp1IEkl40q69WIQRaN"
    ["permissions"]=> array(1) {
      [0]=> string(11) "forum:admin"
    }
    ["org_id"]=> string(26) "org_0v1zWRHJVm7JY8vUqDRuyx"
    ["org"]=> array(8) { ... }
    ["user_id"]=> string(26) "usr_0v1zUpWdE4IiFc2w5ynShf"
    ["user"]=> array(16) { ... }
    ["object"]=> string(10) "membership"
    ["expires_at"]=> NULL
  }
#<AuthRocket::Membership:0x3fc21ab07f40>
  id: "mb_0v1zWp1IEkl40q69WIQRaN",
  attribs: {
    "permissions"=>["forum:admin"],
    "org"=>#<AuthRocket::Org:0x3fc21aaf2a00>
      id: "org_0v1zWRHJVm7JY8vUqDRuyx",
      attribs: {
        "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
        "name"=>"Widgets Inc",
        "state"=>"active",
        "reference"=>nil,
        "object"=>"org",
        "created_at"=>1397249256.259,
        "custom"=>{}
      },
    "org_id"=>"org_0v1zWRHJVm7JY8vUqDRuyx",
    "user"=>#<AuthRocket::User:0x3fc21aaf3acc>
      id: "usr_0v1zUpWdE4IiFc2w5ynShf",
      attribs: {
        "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
        "username"=>"dave",
        "state"=>"active",
        "reference"=>nil,
        "name"=>"dave",
        "email"=>"dave@example.com",
        "object"=>"user",
        "last_login_at"=>null,
        "created_at"=>1392447538.275,
        "first_name"=>nil,
        "last_name"=>nil,
        "custom"=>{}
      },
    "user_id"=>"usr_0v1zUpWdE4IiFc2w5ynShf",
    "object"=>"membership",
    "expires_at"=>nil
  }

Create a membership

Create a new membership.

Request

Example
POST /v2/memberships

{ "membership" :
  { "user_id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
    "org_id"  : "org_0v1zWRHJVm7JY8vUqDRuyx",
    "permissions": ["forum:admin"]
  }
}

var resp = await authrocket.memberships.create({
  user_id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  org_id: "org_0v1zWRHJVm7JY8vUqDRuyx",
  permissions: ["forum:admin"]
})
$res = $authrocket->memberships->create([
  "user_id" => "usr_0v1zUpWdE4IiFc2w5ynShf",
  "org_id" => "org_0v1zWRHJVm7JY8vUqDRuyx",
  "permissions" => ["forum:admin"]
]);
membership = AuthRocket::Membership.create(
  user_id: "usr_0v1zUpWdE4IiFc2w5ynShf",
  org_id: "org_0v1zWRHJVm7JY8vUqDRuyx",
  permissions: ["forum:admin"]
)

Response

Example

Status: 201, with same body as Get a Membership.

On success, returns same object as Get a Membership.

On failure, returns an object with errors:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["User not found"]

On success, returns same object as Get a Membership.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(14) "User not found"
  }

On success, returns same object as Get a Membership.

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

# => #<AuthRocket::Membership:0x3fde5fa18df8> id: nil, ...
membership.errors?
# => true
membership.valid?
# => false
membership.errors
# => ["User not found"]

Events

Triggers a membership.created event.

Update a membership

Update a membership’s permissions. Only provided attributes are changed.

org_id and user_id may not be changed; replace the entire membership instead.

Request

Example
PUT /v2/memberships/:membership_id

{ "membership" :
  { "permissions" : ["forum:admin", "forum:moderator"]
  }
}

Permissions may also be submitted as a single string, space delimited (but will be returned as an array):

{ "membership" :
  { "permissions" : "forum:admin forum:moderator"
  }
}

var resp = await authrocket.memberships.update('mb_0v1zWp1IEkl40q69WIQRaN', {
  permissions: ["forum:admin", "forum:moderator"]
})
$res = $authrocket->memberships->update('mb_0v1zWp1IEkl40q69WIQRaN', [
  "permissions" => ["forum:admin", "forum:moderator"]
]);
membership = AuthRocket::Membership.find 'mb_0v1zWp1IEkl40q69WIQRaN'
membership.update permissions: ["forum:admin", "forum:moderator"]

Response

Example

Status: 200, with same body as Get a Membership.

On success, returns same object as Get a Membership.

On failure, returns an object with errors:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["User not found"]

On success, returns same object as Get a Membership.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(14) "User not found"
  }

On success, returns same object as Get a Membership.

On failure, returns false:

# => false
membership.errors
# => ["User not found"]

Events

Triggers a membership.updated event.

Delete a membership

Deletes a membership.

Request

Example
DELETE /v2/memberships/:membership_id

var resp = await authrocket.memberships.delete('mb_0v1zWp1IEkl40q69WIQRaN')
$res = $authrocket->memberships->delete('mb_0v1zWp1IEkl40q69WIQRaN');
membership = AuthRocket::Membership.find 'mb_0v1zWp1IEkl40q69WIQRaN'
membership.delete

Response

Example

Status: 204

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

Triggers a membership.deleted event.

Contents
Fields Required permissions List memberships for a user or an org Get a membership Create a membership Update a membership Delete a membership