Memberships

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Membership’s ID. Always starts with “mb_”. Example: mb_USl2uVyowwMB2FkI3EbCs

org_id org_id Optional
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.
custom hash Optional Hash of custom attributes.
request hash

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

org_id & user_id

If org_id is blank, the membership will only belong to the user. For apps that don’t use Orgs, this still provides a way to attach permissions to the User (see next section for various uses of permissions). Only one membership per user without an org_id is allowed.

Likewise, only 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.

Custom attributes

See Custom attributes under Users for details.

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 /v1/memberships?org_id=org_0v1zWRHJVm7JY8vUqDRuyx
GET /v1/memberships?user_id=usr_0v1zUpWdE4IiFc2w5ynShf
$res = $client->memberships()->all(['org_id' => 'org_0v1zWRHJVm7JY8vUqDRuyx']);
$res = $client->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,
      "custom" : {},
      "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(8) {
      ["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
      ["custom"]=> array(0) {}
    }
  }
[#<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,
    "custom"=>{}
  },
  metadata: {
    "more_results"=>false
  }
]

Get a membership

Retrieve a specific membership.

Request

Example
GET /v1/memberships/:membership_id
$res = $client->memberships()->find('mb_0v1zWp1IEkl40q69WIQRaN');
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,
  "custom" : {},
  "user" : {
    "id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
    "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
    "username" : "dave",
    "state" : "active",
    "user_type" : "human",
    "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(8) {
    ["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
    ["custom"]=> array(0) {}
  }
#<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",
        "user_type"=>"human",
        "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,
    "custom"=>{}
  }

Create a membership

Create a new membership.

Request

Example
POST /v1/memberships
{ "membership" :
  { "user_id" : "usr_0v1zUpWdE4IiFc2w5ynShf",
    "org_id"  : "org_0v1zWRHJVm7JY8vUqDRuyx",
    "permissions": ["forum:admin"]
  }
}
$res = $client->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:

$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 /v1/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"
  }
}
$res = $client->memberships()->update('mb_0v1zWp1IEkl40q69WIQRaN', [
  "permissions" => ["forum:admin", "forum:moderator"]
]);
membership=AuthRocket::Membership.find 'mb_0v1zWp1IEkl40q69WIQRaN'
membership.save 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:

$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 /v1/memberships/:membership_id
$res = $client->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.

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

On success, returns original object.

On failure, returns false.

Events

Triggers a membership.deleted event.

Questions? Find a Typo? Get in touch.