Memberships

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Membership’s ID. Starts with “mb_”. Example: mb_0v1zUpWdE4IiFc2w5ynShf
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_sample123456
GET /v2/memberships?user_id=usr_sample123456

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

Response

Example

Status: 200

{
  "collection": [
    {
      "expires_at": null,
      "id": "mb_sample123456",
      "object": "membership",
      "org": {
        "created_at": 1704067200.0,
        "id": "org_sample123456",
        "name": "Widgets Inc",
        "object": "org",
        "realm_id": "rl_sample123456",
        "reference": null,
        "state": "active"
      },
      "org_id": "org_sample123456",
      "permissions": [
        "forum:admin"
      ],
      "user_id": "usr_sample123456"
    }
  ],
  "more_results": false
}

// console.log(resp.results)
[
  {
    expires_at: null,
    id: "mb_sample123456",
    object: "membership",
    org: {
      created_at: 1704067200.0,
      id: "org_sample123456",
      name: "Widgets Inc",
      object: "org",
      realm_id: "rl_sample123456",
      reference: null,
      state: "active"
    },
    org_id: "org_sample123456",
    permissions: [
      "forum:admin"
    ],
    user_id: "usr_sample123456"
  }
]
// var_dump($res->results);
array(1) {
  [0]=> 
    array(7) {
      ["expires_at"]=> NULL
      ["id"]=> string(15) "mb_sample123456"
      ["object"]=> string(10) "membership"
      ["org"]=> 
        array(7) {
          ["created_at"]=> float(1704067200.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"
        }
      ["org_id"]=> string(16) "org_sample123456"
      ["permissions"]=> 
        array(1) {
          [0]=> string(11) "forum:admin"
        }
      ["user_id"]=> string(16) "usr_sample123456"
    }
}
[AuthRocket::Membership(
  expires_at: nil,
  id: "mb_sample123456",
  org: 
   AuthRocket::Org(
    created_at: 2024-01-01 00:00:00 UTC,
    id: "org_sample123456",
    name: "Widgets Inc",
    realm_id: "rl_sample123456",
    reference: nil,
    state: "active"
   ),
  org_id: "org_sample123456",
  permissions: ["forum:admin"],
  user_id: "usr_sample123456"
 )
]

Get a membership

Retrieve a specific membership.

Request

Example
GET /v2/memberships/mb_sample123456

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

Response

Example

Status: 200

{
  "expires_at": null,
  "id": "mb_sample123456",
  "object": "membership",
  "org": {
    "created_at": 1704067200.0,
    "custom": {},
    "id": "org_sample123456",
    "name": "Widgets Inc",
    "object": "org",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active"
  },
  "org_id": "org_sample123456",
  "permissions": [
    "forum:admin"
  ],
  "user": {
    "created_at": 1704067200.0,
    "custom": {},
    "email": "davy@example.com",
    "email_pending": null,
    "email_verification": "none",
    "first_name": "Davy",
    "id": "usr_sample123456",
    "last_login_at": null,
    "last_name": "Crockett",
    "locale": null,
    "name": "Davy Crockett",
    "object": "user",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active",
    "username": "davy"
  },
  "user_id": "usr_sample123456"
}

// console.log(resp.results)
{
  expires_at: null,
  id: "mb_sample123456",
  object: "membership",
  org: {
    created_at: 1704067200.0,
    custom: {},
    id: "org_sample123456",
    name: "Widgets Inc",
    object: "org",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active"
  },
  org_id: "org_sample123456",
  permissions: [
    "forum:admin"
  ],
  user: {
    created_at: 1704067200.0,
    custom: {},
    email: "davy@example.com",
    email_pending: null,
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_login_at: null,
    last_name: "Crockett",
    locale: null,
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active",
    username: "davy"
  },
  user_id: "usr_sample123456"
}
// var_dump($res->fields);
array(8) {
  ["expires_at"]=> NULL
  ["id"]=> string(15) "mb_sample123456"
  ["object"]=> string(10) "membership"
  ["org"]=> 
    array(8) {
      ["created_at"]=> float(1704067200.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"
    }
  ["org_id"]=> string(16) "org_sample123456"
  ["permissions"]=> 
    array(1) {
      [0]=> string(11) "forum:admin"
    }
  ["user"]=> 
    array(16) {
      ["created_at"]=> float(1704067200.0)
      ["custom"]=> array(0) {}
      ["email"]=> string(16) "davy@example.com"
      ["email_pending"]=> NULL
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_login_at"]=> NULL
      ["last_name"]=> string(8) "Crockett"
      ["locale"]=> NULL
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["username"]=> string(4) "davy"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}
AuthRocket::Membership(
 expires_at: nil,
 id: "mb_sample123456",
 org: 
  AuthRocket::Org(
   created_at: 2024-01-01 00:00:00 UTC,
   custom: {},
   id: "org_sample123456",
   name: "Widgets Inc",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active"
  ),
 org_id: "org_sample123456",
 permissions: ["forum:admin"],
 user: 
  AuthRocket::User(
   created_at: 2024-01-01 00:00:00 UTC,
   custom: {},
   email: "davy@example.com",
   email_pending: nil,
   email_verification: "none",
   first_name: "Davy",
   id: "usr_sample123456",
   last_login_at: nil,
   last_name: "Crockett",
   locale: nil,
   name: "Davy Crockett",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active",
   username: "davy"
  ),
 user_id: "usr_sample123456"
)

Create a membership

Create a new membership.

Request

Example
POST /v2/memberships

{
  "membership": {
    "org_id": "org_sample123456",
    "permissions": [
      "forum:admin"
    ],
    "user_id": "usr_sample123456"
  }
}

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

Response

Example

On success, status 201 with the new Membership.

{
  "expires_at": null,
  "id": "mb_sample123456",
  "new_record": true,
  "object": "membership",
  "org": {
    "created_at": 1704067200.0,
    "custom": {},
    "id": "org_sample123456",
    "name": "Widgets Inc",
    "object": "org",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active"
  },
  "org_id": "org_sample123456",
  "permissions": [
    "forum:admin"
  ],
  "user": {
    "created_at": 1704067200.0,
    "custom": {},
    "email": "davy@example.com",
    "email_pending": null,
    "email_verification": "none",
    "first_name": "Davy",
    "id": "usr_sample123456",
    "last_login_at": null,
    "last_name": "Crockett",
    "locale": null,
    "name": "Davy Crockett",
    "object": "user",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active",
    "username": "davy"
  },
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success, returns an object with the new Membership.

// console.log(resp.results)
{
  expires_at: null,
  id: "mb_sample123456",
  new_record: true,
  object: "membership",
  org: {
    created_at: 1704067200.0,
    custom: {},
    id: "org_sample123456",
    name: "Widgets Inc",
    object: "org",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active"
  },
  org_id: "org_sample123456",
  permissions: [
    "forum:admin"
  ],
  user: {
    created_at: 1704067200.0,
    custom: {},
    email: "davy@example.com",
    email_pending: null,
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_login_at: null,
    last_name: "Crockett",
    locale: null,
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active",
    username: "davy"
  },
  user_id: "usr_sample123456"
}

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

On success, returns an object with the new Membership.

// var_dump($res->fields);
array(9) {
  ["expires_at"]=> NULL
  ["id"]=> string(15) "mb_sample123456"
  ["new_record"]=> bool(true)
  ["object"]=> string(10) "membership"
  ["org"]=> 
    array(8) {
      ["created_at"]=> float(1704067200.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"
    }
  ["org_id"]=> string(16) "org_sample123456"
  ["permissions"]=> 
    array(1) {
      [0]=> string(11) "forum:admin"
    }
  ["user"]=> 
    array(16) {
      ["created_at"]=> float(1704067200.0)
      ["custom"]=> array(0) {}
      ["email"]=> string(16) "davy@example.com"
      ["email_pending"]=> NULL
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_login_at"]=> NULL
      ["last_name"]=> string(8) "Crockett"
      ["locale"]=> NULL
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["username"]=> string(4) "davy"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

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

On success, returns an object with the new Membership.

AuthRocket::Membership(
 expires_at: nil,
 id: "mb_sample123456",
 new_record: true,
 org: 
  AuthRocket::Org(
   created_at: 2024-01-01 00:00:00 UTC,
   custom: {},
   id: "org_sample123456",
   name: "Widgets Inc",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active"
  ),
 org_id: "org_sample123456",
 permissions: ["forum:admin"],
 user: 
  AuthRocket::User(
   created_at: 2024-01-01 00:00:00 UTC,
   custom: {},
   email: "davy@example.com",
   email_pending: nil,
   email_verification: "none",
   first_name: "Davy",
   id: "usr_sample123456",
   last_login_at: nil,
   last_name: "Crockett",
   locale: nil,
   name: "Davy Crockett",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active",
   username: "davy"
  ),
 user_id: "usr_sample123456"
)

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

Events

Triggers a membership.created event.

Update a membership

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

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

Request

Example
PUT /v2/memberships/mb_sample123456

{
  "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_sample123456", {
  permissions: ["forum:admin", "forum:moderator"]
})
$res = $authrocket->memberships->update("mb_sample123456", [
  "permissions" => ["forum:admin", "forum:moderator"]
]);
membership = AuthRocket::Membership.find "mb_sample123456"
membership.update permissions: ["forum:admin", "forum:moderator"]

Response

Example

On success, status 200 with the updated Membership.

{
  "expires_at": null,
  "id": "mb_sample123456",
  "object": "membership",
  "org": {
    "created_at": 1704067200.0,
    "custom": {},
    "id": "org_sample123456",
    "name": "Widgets Inc",
    "object": "org",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active"
  },
  "org_id": "org_sample123456",
  "permissions": [
    "forum:admin",
    "forum:moderator"
  ],
  "user": {
    "created_at": 1704067200.0,
    "custom": {},
    "email": "davy@example.com",
    "email_pending": null,
    "email_verification": "none",
    "first_name": "Davy",
    "id": "usr_sample123456",
    "last_login_at": null,
    "last_name": "Crockett",
    "locale": null,
    "name": "Davy Crockett",
    "object": "user",
    "realm_id": "rl_sample123456",
    "reference": null,
    "state": "active",
    "username": "davy"
  },
  "user_id": "usr_sample123456"
}

On failure, status 422 with a standard error response.

On success, returns an object with the updated Membership.

// console.log(resp.results)
{
  expires_at: null,
  id: "mb_sample123456",
  object: "membership",
  org: {
    created_at: 1704067200.0,
    custom: {},
    id: "org_sample123456",
    name: "Widgets Inc",
    object: "org",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active"
  },
  org_id: "org_sample123456",
  permissions: [
    "forum:admin",
    "forum:moderator"
  ],
  user: {
    created_at: 1704067200.0,
    custom: {},
    email: "davy@example.com",
    email_pending: null,
    email_verification: "none",
    first_name: "Davy",
    id: "usr_sample123456",
    last_login_at: null,
    last_name: "Crockett",
    locale: null,
    name: "Davy Crockett",
    object: "user",
    realm_id: "rl_sample123456",
    reference: null,
    state: "active",
    username: "davy"
  },
  user_id: "usr_sample123456"
}

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

On success, returns an object with the updated Membership.

// var_dump($res->fields);
array(8) {
  ["expires_at"]=> NULL
  ["id"]=> string(15) "mb_sample123456"
  ["object"]=> string(10) "membership"
  ["org"]=> 
    array(8) {
      ["created_at"]=> float(1704067200.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"
    }
  ["org_id"]=> string(16) "org_sample123456"
  ["permissions"]=> 
    array(2) {
      [0]=> string(11) "forum:admin"
      [1]=> string(15) "forum:moderator"
    }
  ["user"]=> 
    array(16) {
      ["created_at"]=> float(1704067200.0)
      ["custom"]=> array(0) {}
      ["email"]=> string(16) "davy@example.com"
      ["email_pending"]=> NULL
      ["email_verification"]=> string(4) "none"
      ["first_name"]=> string(4) "Davy"
      ["id"]=> string(16) "usr_sample123456"
      ["last_login_at"]=> NULL
      ["last_name"]=> string(8) "Crockett"
      ["locale"]=> NULL
      ["name"]=> string(13) "Davy Crockett"
      ["object"]=> string(4) "user"
      ["realm_id"]=> string(15) "rl_sample123456"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["username"]=> string(4) "davy"
    }
  ["user_id"]=> string(16) "usr_sample123456"
}

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

On success, returns an object with the updated Membership.

AuthRocket::Membership(
 expires_at: nil,
 id: "mb_sample123456",
 org: 
  AuthRocket::Org(
   created_at: 2024-01-01 00:00:00 UTC,
   custom: {},
   id: "org_sample123456",
   name: "Widgets Inc",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active"
  ),
 org_id: "org_sample123456",
 permissions: ["forum:admin", "forum:moderator"],
 user: 
  AuthRocket::User(
   created_at: 2024-01-01 00:00:00 UTC,
   custom: {},
   email: "davy@example.com",
   email_pending: nil,
   email_verification: "none",
   first_name: "Davy",
   id: "usr_sample123456",
   last_login_at: nil,
   last_name: "Crockett",
   locale: nil,
   name: "Davy Crockett",
   realm_id: "rl_sample123456",
   reference: nil,
   state: "active",
   username: "davy"
  ),
 user_id: "usr_sample123456"
)

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

Events

Triggers a membership.updated event.

Delete a membership

Deletes a membership.

Request

Example
DELETE /v2/memberships/mb_sample123456

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

Response

Example

On success, status 204 with an empty response.
On failure, status 422 with a standard error response.

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

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

On success, returns the original object with no errors.
On failure, returns false with errors added to original object.

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