Invitations

Fields

Field	Value	Req/Default	Notes
`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

Method	Permissions
List, Get	read
Create, Update, Invite, Delete	write

List invitations

List all invitations for a realm or an org.

Parameters

Param	Value	Default
`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.

Invitations

Fields

invitation_type: org

invitation_type: preverify

invitation_type: referral

invitation_type: request

Permissions

Events

Required permissions

List invitations

Parameters

Request

Example

Response

Example

Get an invitation

Request

Example

Response

Example

Create an invitation

Request

Example

Response

Example

Events

Update an invitation

Request

Example

Response

Example

Events

Send the actual invitation

Request

Example

Response

Example

Events

Delete an invitation

Request

Example

Response

Example

Events

Accept an invitation

Request

Example

Response

Example

Events

Contents

invitation_type: `org`

invitation_type: `preverify`

invitation_type: `referral`

invitation_type: `request`