Field | Value | Req/Default | Notes |
---|---|---|---|
id |
id | Auto-generated | Membership’s ID. Always starts with “mb_”. Example: |
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. |
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 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.
See Custom attributes under Users for details.
Method | Permissions |
---|---|
List, Get | read |
Create, Update, Delete | write |
List all memberships associated with a specific user or org.
Param | Value | Default | |
---|---|---|---|
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.
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'
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
}
]
Retrieve a specific membership.
GET /v1/memberships/:membership_id
$res = $client->memberships()->find('mb_0v1zWp1IEkl40q69WIQRaN');
AuthRocket::Membership.find 'mb_0v1zWp1IEkl40q69WIQRaN'
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 new membership.
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"]
)
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"]
Triggers a membership.created
event.
Update a membership’s permissions. Only provided attributes are changed.
org_id
and user_id
may not be changed; replace the entire membership instead.
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"]
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"]
Triggers a membership.updated
event.
Deletes a membership.
DELETE /v1/memberships/:membership_id
$res = $client->memberships()->delete('mb_0v1zWp1IEkl40q69WIQRaN');
membership=AuthRocket::Membership.find 'mb_0v1zWp1IEkl40q69WIQRaN'
membership.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 a membership.deleted
event.
Questions? Find a Typo? Get in touch.