Invitations
Fields
Field | Value | Req/Default | Notes |
---|---|---|---|
id |
id | Auto-generated | Invitation’s ID. Starts with “nvt_”. Example: |
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. May match |
|
|||
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. |
|
|||
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, Accept | 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 |
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
{
"collection": [
{
"created_at": 1735689600.0,
"email": "davy@example.com",
"expires_at": null,
"id": "nvt_sample123456",
"invitation_type": "request",
"invited_at": null,
"locale": null,
"object": "invitation",
"realm_id": "rl_sample123456",
"token": "nvt_sample123456"
}
],
"more_results": false
}
// console.log(resp.results)
[
{
created_at: 1735689600.0,
email: "davy@example.com",
expires_at: null,
id: "nvt_sample123456",
invitation_type: "request",
invited_at: null,
locale: null,
object: "invitation",
realm_id: "rl_sample123456",
token: "nvt_sample123456"
}
]
// var_dump($res->results);
array(1) {
[0]=>
array(10) {
["created_at"]=> float(1735689600.0)
["email"]=> string(16) "davy@example.com"
["expires_at"]=> NULL
["id"]=> string(16) "nvt_sample123456"
["invitation_type"]=> string(7) "request"
["invited_at"]=> NULL
["locale"]=> NULL
["object"]=> string(10) "invitation"
["realm_id"]=> string(15) "rl_sample123456"
["token"]=> string(16) "nvt_sample123456"
}
}
[AuthRocket::Invitation(
created_at: 2025-01-01 00:00:00 UTC,
email: "davy@example.com",
expires_at: nil,
id: "nvt_sample123456",
invitation_type: "request",
invited_at: nil,
locale: nil,
realm_id: "rl_sample123456",
token: "nvt_sample123456"
)
]
Get an invitation
Retrieve a specific invitation.
Request
Example
GET /v2/invitations/nvt_sample123456
var resp = await authrocket.invitations.find("nvt_sample123456")
$res = $authrocket->invitations->find("nvt_sample123456");
invitation = AuthRocket::Invitation.find "nvt_sample123456"
Response
Example
Status: 200
{
"created_at": 1735689600.0,
"email": "davy@example.com",
"expires_at": null,
"id": "nvt_sample123456",
"invitation_type": "request",
"invited_at": null,
"locale": null,
"object": "invitation",
"realm_id": "rl_sample123456",
"token": "nvt_sample123456"
}
// console.log(resp.results)
{
created_at: 1735689600.0,
email: "davy@example.com",
expires_at: null,
id: "nvt_sample123456",
invitation_type: "request",
invited_at: null,
locale: null,
object: "invitation",
realm_id: "rl_sample123456",
token: "nvt_sample123456"
}
// var_dump($res->fields);
array(10) {
["created_at"]=> float(1735689600.0)
["email"]=> string(16) "davy@example.com"
["expires_at"]=> NULL
["id"]=> string(16) "nvt_sample123456"
["invitation_type"]=> string(7) "request"
["invited_at"]=> NULL
["locale"]=> NULL
["object"]=> string(10) "invitation"
["realm_id"]=> string(15) "rl_sample123456"
["token"]=> string(16) "nvt_sample123456"
}
AuthRocket::Invitation(
created_at: 2025-01-01 00:00:00 UTC,
email: "davy@example.com",
expires_at: nil,
id: "nvt_sample123456",
invitation_type: "request",
invited_at: nil,
locale: nil,
realm_id: "rl_sample123456",
token: "nvt_sample123456"
)
Create an invitation
Create a new invitation.
Request
Example
POST /v2/invitations
{
"invitation": {
"email": "davy@example.com",
"invitation_type": "org",
"org_id": "org_sample123456",
"permissions": [
"forum:member"
]
}
}
var resp = await authrocket.invitations.create({
email: "davy@example.com",
invitation_type: "org",
org_id: "org_sample123456",
permissions: ["forum:member"]
})
$res = $authrocket->invitations->create([
"email" => "davy@example.com",
"invitation_type" => "org",
"org_id" => "org_sample123456",
"permissions" => ["forum:member"]
]);
invitation = AuthRocket::Invitation.create(
email: "davy@example.com",
invitation_type: "org",
org_id: "org_sample123456",
permissions: ["forum:member"]
)
Response
Example
On success, status 201 with the new Invitation.
{
"created_at": 1735689600.0,
"email": "davy@example.com",
"expires_at": 1738281600,
"id": "nvt_sample123456",
"invitation_type": "org",
"invited_at": 1735689600,
"inviting_user_id": null,
"locale": null,
"object": "invitation",
"org": {
"created_at": 1735689600.0,
"custom": {},
"id": "org_sample123456",
"name": "Widgets Inc",
"object": "org",
"realm_id": "rl_sample123456",
"reference": null,
"state": "active"
},
"org_id": "org_sample123456",
"permissions": [
"forum:member"
],
"realm_id": "rl_sample123456",
"token": "nvt_sample123456"
}
On failure, status 422 with a standard error response.
On success, returns an object with the new Invitation.
// console.log(resp.results)
{
created_at: 1735689600.0,
email: "davy@example.com",
expires_at: 1738281600,
id: "nvt_sample123456",
invitation_type: "org",
invited_at: 1735689600,
inviting_user_id: null,
locale: null,
object: "invitation",
org: {
created_at: 1735689600.0,
custom: {},
id: "org_sample123456",
name: "Widgets Inc",
object: "org",
realm_id: "rl_sample123456",
reference: null,
state: "active"
},
org_id: "org_sample123456",
permissions: [
"forum:member"
],
realm_id: "rl_sample123456",
token: "nvt_sample123456"
}
On failure, returns an object with a standard error response.
On success, returns an object with the new Invitation.
// var_dump($res->fields);
array(14) {
["created_at"]=> float(1735689600.0)
["email"]=> string(16) "davy@example.com"
["expires_at"]=> int(1738281600)
["id"]=> string(16) "nvt_sample123456"
["invitation_type"]=> string(3) "org"
["invited_at"]=> int(1735689600)
["inviting_user_id"]=> NULL
["locale"]=> NULL
["object"]=> string(10) "invitation"
["org"]=>
array(8) {
["created_at"]=> float(1735689600.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(12) "forum:member"
}
["realm_id"]=> string(15) "rl_sample123456"
["token"]=> string(16) "nvt_sample123456"
}
On failure, returns an object with a standard error response.
On success, returns an object with the new Invitation.
AuthRocket::Invitation(
created_at: 2025-01-01 00:00:00 UTC,
email: "davy@example.com",
expires_at: 2025-01-31 00:00:00 UTC,
id: "nvt_sample123456",
invitation_type: "org",
invited_at: 2025-01-01 00:00:00 UTC,
inviting_user_id: nil,
locale: nil,
org:
AuthRocket::Org(
created_at: 2025-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:member"],
realm_id: "rl_sample123456",
token: "nvt_sample123456"
)
On failure, returns an object with a standard error response.
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/nvt_sample123456
{
"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_sample123456", {
permissions: ["forum:admin", "forum:moderator"]
})
$res = $authrocket->invitations->update("nvt_sample123456", [
"permissions" => ["forum:admin", "forum:moderator"]
]);
invitation = AuthRocket::Invitation.find "nvt_sample123456"
invitation.update permissions: ["forum:admin", "forum:moderator"]
Response
Example
On success, status 200 with the updated Invitation.
{
"created_at": 1735689600.0,
"email": "davy@example.com",
"expires_at": 1738281600,
"id": "nvt_sample123456",
"invitation_type": "org",
"invited_at": 1735689600,
"inviting_user_id": null,
"locale": null,
"object": "invitation",
"org": {
"created_at": 1735689600.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"
],
"realm_id": "rl_sample123456",
"token": "nvt_sample123456"
}
On failure, status 422 with a standard error response.
On success, returns an object with the updated Invitation.
// console.log(resp.results)
{
created_at: 1735689600.0,
email: "davy@example.com",
expires_at: 1738281600,
id: "nvt_sample123456",
invitation_type: "org",
invited_at: 1735689600,
inviting_user_id: null,
locale: null,
object: "invitation",
org: {
created_at: 1735689600.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"
],
realm_id: "rl_sample123456",
token: "nvt_sample123456"
}
On failure, returns an object with a standard error response.
On success, returns an object with the updated Invitation.
// var_dump($res->fields);
array(14) {
["created_at"]=> float(1735689600.0)
["email"]=> string(16) "davy@example.com"
["expires_at"]=> int(1738281600)
["id"]=> string(16) "nvt_sample123456"
["invitation_type"]=> string(3) "org"
["invited_at"]=> int(1735689600)
["inviting_user_id"]=> NULL
["locale"]=> NULL
["object"]=> string(10) "invitation"
["org"]=>
array(8) {
["created_at"]=> float(1735689600.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"
}
["realm_id"]=> string(15) "rl_sample123456"
["token"]=> string(16) "nvt_sample123456"
}
On failure, returns an object with a standard error response.
On success, returns an object with the updated Invitation.
AuthRocket::Invitation(
created_at: 2025-01-01 00:00:00 UTC,
email: "davy@example.com",
expires_at: 2025-01-31 00:00:00 UTC,
id: "nvt_sample123456",
invitation_type: "org",
invited_at: 2025-01-01 00:00:00 UTC,
inviting_user_id: nil,
locale: nil,
org:
AuthRocket::Org(
created_at: 2025-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"],
realm_id: "rl_sample123456",
token: "nvt_sample123456"
)
On failure, returns an object with a standard error response.
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. New realms include a default email hook for sending invitations, but this may be marked inactive or replaced with a webhook.
Parameters
Param | Value | Default | |
---|---|---|---|
expires_at |
time_t | +30 days |
If previously sent, default=unchanged instead. Upon expiration, invitation is automatically deleted. |
Request
Example
POST /v2/invitations/nvt_sample123456/invite
var resp = await authrocket.invitations.invite("nvt_sample123456")
$res = $authrocket->invitations->invite("nvt_sample123456");
invitation = AuthRocket::Invitation.find "nvt_sample123456"
invitation.invite
Response
Example
On success, status 200 with the updated Invitation.
{
"created_at": 1735689600.0,
"email": "davy@example.com",
"expires_at": 1738286580,
"id": "nvt_sample123456",
"invitation_type": "request",
"invited_at": 1735694580,
"locale": null,
"object": "invitation",
"realm_id": "rl_sample123456",
"token": "nvt_sample123456"
}
On failure, status 422 with a standard error response.
On success, returns an object with the updated Invitation.
// console.log(resp.results)
{
created_at: 1735689600.0,
email: "davy@example.com",
expires_at: 1738286580,
id: "nvt_sample123456",
invitation_type: "request",
invited_at: 1735694580,
locale: null,
object: "invitation",
realm_id: "rl_sample123456",
token: "nvt_sample123456"
}
On failure, returns an object with a standard error response.
On success, returns an object with the updated Invitation.
// var_dump($res->fields);
array(10) {
["created_at"]=> float(1735689600.0)
["email"]=> string(16) "davy@example.com"
["expires_at"]=> int(1738286580)
["id"]=> string(16) "nvt_sample123456"
["invitation_type"]=> string(7) "request"
["invited_at"]=> int(1735694580)
["locale"]=> NULL
["object"]=> string(10) "invitation"
["realm_id"]=> string(15) "rl_sample123456"
["token"]=> string(16) "nvt_sample123456"
}
On failure, returns an object with a standard error response.
On success, returns an object with the updated Invitation.
AuthRocket::Invitation(
created_at: 2025-01-01 00:00:00 UTC,
email: "davy@example.com",
expires_at: 2025-01-31 01:23:00 UTC,
id: "nvt_sample123456",
invitation_type: "request",
invited_at: 2025-01-01 01:23:00 UTC,
locale: nil,
realm_id: "rl_sample123456",
token: "nvt_sample123456"
)
On failure, returns an object with a standard error response.
Events
Triggers an invitation.*.invited
event.
Delete an invitation
Deletes (immediately expires) an invitation.
Request
Example
DELETE /v2/invitations/nvt_sample123456
var resp = await authrocket.invitations.delete("nvt_sample123456")
$res = $authrocket->invitations->delete("nvt_sample123456");
invitation = AuthRocket::Invitation.find "nvt_sample123456"
invitation.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 an invitation.*.expired
event.
Accept an invitation to an org
Accepts an invitation for the given user using token
.
Creates a membership to link the user to the invitation’s org. If such membership already exists, permissions
are merged.
Request
Example
POST /v2/users/:user_id/accept_invitation
{
"user": {
"token": "nvt_sample123456"
}
}
var resp = await authrocket.users.acceptInvitation("usr_sample123456", {
token: "nvt_sample123456"
})
$res = $authrocket->users->acceptInvitation("usr_sample123456", [
"token" => "nvt_sample123456"
]);
user = AuthRocket::User.find "usr_sample123456"
res = user.accept_invitation token: "nvt_sample123456"
Response
Example
On success, status 200 with the updated User.
{
"created_at": 1735689600.0,
"credentials": [
{
"credential_type": "password",
"id": "crd_sample123456",
"object": "credential"
}
],
"custom": {},
"email": "davy@example.com",
"email_pending": null,
"email_verification": "verified",
"first_name": "Davy",
"id": "usr_sample123456",
"last_login_at": null,
"last_name": "Crockett",
"locale": null,
"membership_count": 1,
"memberships": [
{
"expires_at": null,
"id": "mb_sample123456",
"new_record": true,
"object": "membership",
"org": {
"created_at": 1735689600.0,
"custom": {},
"id": "org_sample123456",
"name": "Widgets Inc",
"object": "org",
"realm_id": "rl_sample123456",
"reference": null,
"state": "active"
},
"org_id": "org_sample123456",
"permissions": [
"forum:member"
],
"user_id": "usr_sample123456"
}
],
"name": "Davy Crockett",
"object": "user",
"realm_id": "rl_sample123456",
"reference": null,
"state": "active",
"username": "davy"
}
On failure, status 422 with a standard error response.
On success, returns an object with the updated User.
// console.log(resp.results)
{
created_at: 1735689600.0,
credentials: [
{
credential_type: "password",
id: "crd_sample123456",
object: "credential"
}
],
custom: {},
email: "davy@example.com",
email_pending: null,
email_verification: "verified",
first_name: "Davy",
id: "usr_sample123456",
last_login_at: null,
last_name: "Crockett",
locale: null,
membership_count: 1,
memberships: [
{
expires_at: null,
id: "mb_sample123456",
new_record: true,
object: "membership",
org: {
created_at: 1735689600.0,
custom: {},
id: "org_sample123456",
name: "Widgets Inc",
object: "org",
realm_id: "rl_sample123456",
reference: null,
state: "active"
},
org_id: "org_sample123456",
permissions: [
"forum:member"
],
user_id: "usr_sample123456"
}
],
name: "Davy Crockett",
object: "user",
realm_id: "rl_sample123456",
reference: null,
state: "active",
username: "davy"
}
On failure, returns an object with a standard error response.
On success, returns an object with the updated User.
// var_dump($res->fields);
array(19) {
["created_at"]=> float(1735689600.0)
["credentials"]=>
array(1) {
[0]=>
array(3) {
["credential_type"]=> string(8) "password"
["id"]=> string(16) "crd_sample123456"
["object"]=> string(10) "credential"
}
}
["custom"]=> array(0) {}
["email"]=> string(16) "davy@example.com"
["email_pending"]=> NULL
["email_verification"]=> string(8) "verified"
["first_name"]=> string(4) "Davy"
["id"]=> string(16) "usr_sample123456"
["last_login_at"]=> NULL
["last_name"]=> string(8) "Crockett"
["locale"]=> NULL
["membership_count"]=> int(1)
["memberships"]=>
array(1) {
[0]=>
array(8) {
["expires_at"]=> NULL
["id"]=> string(15) "mb_sample123456"
["new_record"]=> bool(true)
["object"]=> string(10) "membership"
["org"]=>
array(8) {
["created_at"]=> float(1735689600.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(12) "forum:member"
}
["user_id"]=> string(16) "usr_sample123456"
}
}
["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"
}
On failure, returns an object with a standard error response.
On success, returns the updated User object.
AuthRocket::User(
created_at: 2025-01-01 00:00:00 UTC,
credentials:
[AuthRocket::Credential(credential_type: "password", id: "crd_sample123456"
)],
custom: {},
email: "davy@example.com",
email_pending: nil,
email_verification: "verified",
first_name: "Davy",
id: "usr_sample123456",
last_login_at: nil,
last_name: "Crockett",
locale: nil,
membership_count: 1,
memberships:
[AuthRocket::Membership(
expires_at: nil,
id: "mb_sample123456",
new_record: true,
org:
AuthRocket::Org(
created_at: 2025-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:member"],
user_id: "usr_sample123456"
)],
name: "Davy Crockett",
realm_id: "rl_sample123456",
reference: nil,
state: "active",
username: "davy"
)
On failure, returns false with errors added to original object.
Events
Triggers an invitation.*.accepted
event.