Invitations

Fields

FieldValueReq/DefaultNotes
id id Auto-generated

Invitation’s ID. Starts with “nvt_”. Example: nvt_0v1zUpWdE4IiFc2w5ynShf

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 id, but don’t assume this.

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, Accept 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

{
  "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

ParamValueDefault
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.