Invitations

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Invitation’s ID. Always starts with “nvt_”. Example: nvt_USl2uVyowwMB2FkI3EbCs
invitation_type org, preverify, referral, request Required Invitation's type.
created_at time_t Auto-generated Time this invitation was created.
email string Required
expires_at time_t +30 days Time after which this invitation will be automatically deleted.
invited_at time_t Auto-generated Time this invitation was sent.
inviting_user_id user_id Optional ID of User initiating the invitation (n/a for type `request`).
locale string Realm's default Locale to use for outbound email.
realm_id realm_id Required ID of Realm this Invitation belongs to.
request hash

Hash of request attributes to add to Event. See notes.
token string Auto-generated Token to be used to accept this invitation.

org only:
org_id org_id Optional ID of Org the user will be added to when accepting the invitation.
permissions string Optional One, or an array of, permission(s) to be granted to the user when accepting the invitation.

preverify only:
auth_provider_id auth_provider_id Optional When present, ID of AuthProvider used to build the OAuth login URL in the outbound email. When blank, URL is normal signup link.

invitation_type: org

Represents a user who has been invited to join a specific Org by one of the Org’s admin users. Upon acceptance, the invited user will be automatically added to the Org with the specified permissions. If the accepting user already has a profile (perhaps with a different email), the new membership will be added to the existing profile. Created by LoginRocket in multi_user account mode as part of team management.

invitation_type: preverify

Represents a user who initiated a signup to your app and needs to verify their email address. Created by LoginRocket when signup mode is ‘open’ /and/ email verifications are ‘preverify’.

invitation_type: referral

Represents a user who has been invited by another user (inviting_user_id) to join your app. Created by LoginRocket in single_user account mode when a user invites another person.

invitation_type: request

Represents a user who is requesting access to your app. Created by LoginRocket when signup mode is ‘invitation’ (request invites).

Permissions

See Permissions under Memberships for details.

Events

Each invitation_type creates its own scoped set of of events. For example, type request will create invitation.request.* events.

Invitations will trigger an invitation.*.expired event upon expiration. If for some reason multiple invitations exist for a single user, when one is accepted, duplicates will be deleted without triggering an event.

Other events are as indicated below.

Required permissions

MethodPermissions
List, Get read
Create, Update, Invite, Delete write

List invitations

List all invitations for a realm or an org.

Parameters

ParamValueDefault
invitation_type string Filter by invitation_type
org_id org_id Filter by org_id
state pending, invited Filter by not-yet-invited / invited
email email Filter by invitee email
after invitation_id ID of the last invitation you've seen
max_results integer 100 Range: 1-1000
sort id, email id
direction asc, desc asc

Request

Example
GET /v2/invitations?invitation_type=request

var resp = await authrocket.invitations.all({invitation_type: 'request'})
$res = $authrocket->invitations->all(['invitation_type' => 'request']);
AuthRocket::Invitation.all invitation_type: 'request'

Response

Example

Status: 200

{ "more_results" : false,
  "collection" : [
    { "id" : "nvt_0v1zWp1IEkl40q69WIQRaN",
      "email" : "jane@example.com",
      "invitation_type" : "request",
      "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
      "object" : "invitation",
      "created_at" : 1399882358,
      "expires_at" : 1402474358,
      "invited_at" : null,
      "token" : "nvt_0v1zWp1IEkl40q69WIQRaN"
    }
  ]
}

console.log(resp.results)
[ { id: "nvt_0v1zWp1IEkl40q69WIQRaN",
    email: "jane@example.com",
    invitation_type: "request",
    realm_id: "rl_0v1zTHXhtNgmDaXaDYSAqx",
    object: "invitation",
    created_at: 1399882358,
    expires_at: 1402474358,
    invited_at: null,
    token: "nvt_0v1zWp1IEkl40q69WIQRaN"
  }
]
var_dump($res->results);
  array(1) {
    [0]=>
    array(9) {
      ["id"]=> string(26) "nvt_0v1zWp1IEkl40q69WIQRaN"
      ["email"]=> string(16) "jane@example.com"
      ["invitation_type"]=> string(7) "request"
      ["realm_id"]=> string(26) "rl_0v1zTHXhtNgmDaXaDYSAqx"
      ["object"]=> string(10) "invitation"
      ["created_at"]=> 1399882358
      ["expires_at"]=> 1402474358
      ["invited_at"]=> null
      ["token"]=> string(26) "nvt_0v1zWp1IEkl40q69WIQRaN"
    }
  }
[#<AuthRocket::Invitation:0x3fc218640acc>
  id: "nvt_0v1zWp1IEkl40q69WIQRaN",
  attribs: {
    "email"=>"jane@example.com",
    "invitation_type"=>"request",
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "object"=>"invitation",
    "created_at"=>1399882358,
    "expires_at"=>1402474358,
    "invited_at"=>nil,
    "token"=>"nvt_0v1zWp1IEkl40q69WIQRaN"
  },
  metadata: {
    "more_results"=>false
  }
]

Get an invitation

Retrieve a specific invitation.

Request

Example
GET /v2/invitations/:invitation_id

var resp = await authrocket.invitations.find('nvt_0v1zWp1IEkl40q69WIQRaN')
$res = $authrocket->invitations->find('nvt_0v1zWp1IEkl40q69WIQRaN');
invitation = AuthRocket::Invitation.find 'nvt_0v1zWp1IEkl40q69WIQRaN'

Response

Example

Status: 200

{ "id" : "nvt_0v1zWp1IEkl40q69WIQRaN",
  "email" : "jane@example.com",
  "invitation_type" : "request",
  "realm_id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
  "object" : "invitation",
  "created_at" : 1399882358,
  "expires_at" : 1402474358,
  "invited_at" : null,
  "token" : "nvt_0v1zWp1IEkl40q69WIQRaN"
}

console.log(resp.results)
{ id: "nvt_0v1zWp1IEkl40q69WIQRaN",
  email: "jane@example.com",
  invitation_type: "request",
  realm_id: "rl_0v1zTHXhtNgmDaXaDYSAqx",
  object: "invitation",
  created_at: 1399882358,
  expires_at: 1402474358,
  invited_at: null,
  token: "nvt_0v1zWp1IEkl40q69WIQRaN"
}
var_dump($res->fields);
  array(9) {
    ["id"]=> string(26) "nvt_0v1zWp1IEkl40q69WIQRaN"
    ["email"]=> string(16) "jane@example.com"
    ["invitation_type"]=> string(7) "request"
    ["realm_id"]=> string(26) "rl_0v1zTHXhtNgmDaXaDYSAqx"
    ["object"]=> string(10) "invitation"
    ["created_at"]=> 1399882358
    ["expires_at"]=> 1402474358
    ["invited_at"]=> null
    ["token"]=> string(26) "nvt_0v1zWp1IEkl40q69WIQRaN"
  }
#<AuthRocket::Invitation:0x3fc218640acc>
  id: "nvt_0v1zWp1IEkl40q69WIQRaN",
  attribs: {
    "email"=>"jane@example.com",
    "invitation_type"=>"request",
    "realm_id"=>"rl_0v1zTHXhtNgmDaXaDYSAqx",
    "object"=>"invitation",
    "created_at"=>1399882358,
    "expires_at"=>1402474358,
    "invited_at"=>nil,
    "token"=>"nvt_0v1zWp1IEkl40q69WIQRaN"
  }

Create an invitation

Create a new invitation.

Request

Example
POST /v2/invitations

{ "invitation" :
  { "invitation_type" : "org",
    "org_id" : "org_0v1zWRHJVm7JY8vUqDRuyx",
    "email" : "jane@example.com"
    "permissions": ["forum:member"]
  }
}

var resp = await authrocket.invitations.create({
  invitation_type: "org",
  org_id: "org_0v1zWRHJVm7JY8vUqDRuyx",
  email: "jane@example.com",
  permissions: ["forum:member"]
})
$res = $authrocket->invitations->create([
  "invitation_type" => "org",
  "org_id" => "org_0v1zWRHJVm7JY8vUqDRuyx",
  "email" => "jane@example.com",
  "permissions" => ["forum:member"]
]);
invitation = AuthRocket::Invitation.create(
  invitation_type: "org",
  org_id: "org_0v1zWRHJVm7JY8vUqDRuyx",
  email: "jane@example.com",
  permissions: ["forum:member"]
)

Response

Example

Status: 201, with same body as Get an Invitation.

On success, returns same object as Get an Invitation.

On failure, returns an object with errors:

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

On success, returns same object as Get an Invitation.

On failure, returns an object with errors:

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

On success, returns same object as Get an Invitation.

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

# => #<AuthRocket::Invitation:0x3fde5fa18df8> id: nil, ...
invitation.errors?
# => true
invitation.valid?
# => false
invitation.errors
# => ["Org not found"]

Events

Triggers an invitation.*.created event.

Update an invitation

Update an invitation. Only provided attributes are changed.

Only expires_at and permissions may be changed. In other cases, replace the invitation instead.

Request

Example
PUT /v2/invitations/:invitation_id

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

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

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

var resp = await authrocket.invitations.update('nvt_0v1zWp1IEkl40q69WIQRaN', {
  permissions: ["forum:admin", "forum:moderator"]
})
$res = $authrocket->invitations->update('nvt_0v1zWp1IEkl40q69WIQRaN', [
  "permissions" => ["forum:admin", "forum:moderator"]
]);
invitation = AuthRocket::Invitation.find 'nvt_0v1zWp1IEkl40q69WIQRaN'
invitation.update permissions: ["forum:admin", "forum:moderator"]

Response

Example

Status: 200, with same body as Get an Invitation.

On success, returns same object as Get an Invitation.

On failure, returns an object with errors:

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

On success, returns same object as Get an Invitation.

On failure, returns an object with errors:

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

On success, returns same object as Get an Invitation.

On failure, returns false:

# => false
invitation.errors
# => ["Org not found"]

Events

Triggers an invitation.*.updated event.

Send the actual invitation

Triggers sending of the actual invitation. If previously sent, will resend. Uses an event trigger to perform the actual send.

Request

Example
POST /v2/invitations/:invitation_id/invite

var resp = await authrocket.invitations.invite('nvt_0v1zWp1IEkl40q69WIQRaN')
$res = $authrocket->invitations->invite('nvt_0v1zWp1IEkl40q69WIQRaN');
invitation = AuthRocket::Invitation.find 'nvt_0v1zWp1IEkl40q69WIQRaN'
invitation.invite

Response

Example

Status: 200, with same body as Get an Invitation.

On success, returns same object as Get an Invitation.

On failure, returns an object with errors:

resp.hasErrors()
// => true
console.log(resp.errors)
// => ["No hook available to send an invitation"]

On success, returns same object as Get an Invitation.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(39) "No hook available to send an invitation"
  }

On success, returns same object as Get an Invitation.

On failure, returns false:

# => false
invitation.errors
# => ["No hook available to send an invitation"]

Events

Triggers an invitation.*.invited event.

Delete an invitation

Deletes (immediately expires) an invitation.

Request

Example
DELETE /v2/invitations/:invitation_id

var resp = await authrocket.invitations.delete('nvt_0v1zWp1IEkl40q69WIQRaN')
$res = $authrocket->invitations->delete('nvt_0v1zWp1IEkl40q69WIQRaN');
invitation = AuthRocket::Invitation.find 'nvt_0v1zWp1IEkl40q69WIQRaN'
invitation.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 an invitation.*.expired event.

Accept an invitation

Accepts an invitation for the given user using the token.

When Invitation.org_id not present, simply marks the invitation as accepted so it cannot be reused.

When org_id is present, creates a Membership as described above and also marks the invitation as accepted.

Request

Example
POST /v2/users/:user_id/accept_invitation/:invitation_token

var resp = await authrocket.users.acceptInvitation('usr_0ve4Xq92G8Kfxq5ZB5SRyw', {
  token: 'nvt_0v1zWp1IEkl40q69WIQRaN'
})
$res = $authrocket->users->acceptInvitation('usr_0ve4Xq92G8Kfxq5ZB5SRyw', [
  'token'=>'nvt_0v1zWp1IEkl40q69WIQRaN'
]);
user = AuthRocket::User.find 'usr_0ve4Xq92G8Kfxq5ZB5SRyw'
res = user.accept_invitation('nvt_0v1zWp1IEkl40q69WIQRaN')

Response

Example

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

On success, returns a User object with no errors.

On failure, returns an object with errors.

resp.hasErrors()
// => true

On success, returns a User object with no errors.

On failure, returns an object with errors.

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

On success, returns original (User) object.

On failure, returns false.

Events

Triggers an invitation.*.accepted event.

Contents
Fields Required permissions List invitations Get an invitation Create an invitation Update an invitation Send the actual invitation Delete an invitation Accept an invitation