Field | Value | Req/Default | Notes |
---|---|---|---|
id |
id | Auto-generated | Membership’s ID. Always starts with “mb_”. Example: |
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. |
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.
Permissions beginning with ar:
are reserved for use by AuthRocket itself. These permissions are currently used:
ar:owner
Indicates which User owns the Orgar:admin
Indicates Users who may manage the Org’s teamMethod | 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 /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'
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
}
]
Retrieve a specific membership.
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'
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 new membership.
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"]
)
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"]
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 /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"]
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"]
Triggers a membership.updated
event.
Deletes a membership.
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
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.
Triggers a membership.deleted
event.