Invites quickstart

How to create, send, and (optionally) process an invite-accepted event.

1. Create an Invite

You can create a secure invite with UserKit's Invite API. This creates an invite object with a secret URL which you can send out in an email.

curl https://api.userkit.io/v1/invites \
 -u api:<YOUR_APP_SECRET_KEY> \
 -H "Content-Type: application/json" \
 -d '{"to_email": "[email protected]", "extras": {"doc_id": "ab123"}}'

uk = userkit.UserKit("<YOUR_APP_SECRET_KEY>")

invite = uk.invites.create_invite(to_email="[email protected]")

<?php

$uk = new UserKit('<YOUR_APP_SECRET_KEY>');

$invite = $uk->invites->createInvite(['to_email' => '[email protected]');

2. Send the invite URL

Now that you've created an invite, you can send the URL stored in invite.invite_url by email, SMS, or however you like.

How you do this is up to you, but you might consider a third-party email service like Mailgun (https://mailgun.com), SendGrid (https://sendgrid.com) or MailJet (https://mjml.io).

# Send an email containing the invite url
email_body = "To join our app click here: {}".format(invite.invite_url)
send_email(to='[email protected]', body=email_body)

<?php

// Send an email containing the invite url
$email_body = "To join our app click here: $invite->invite_url";
send_email(['to' => '[email protected]', 'body' => $email_body);

When the recipient clicks on the invite link, the invite object will be updated (accepted will be set to true, and accepted_user will be set to this user's id).

📘
By default, invite URLs point to a page hosted by UserKit. You can change this to a page on your own domain where you host the UserKit widget, such as your account page. See the "Widget URL" section in the dashboard under Settings.

If you want to do something special (like add the invited user to a team, or grant them access to a shared document) see step 3, otherwise you're finished!

3. Handle invite-accepted callback (optional)

If you want to do something special when an invite is accepted, such as add the invited user to a team or give them access to a shared document, you can override the UserKit.onInviteAccepted() method on the page where you are hosting the widget.

📘
When you create an invite you can add some custom data to it by passing in the extras parameter. When you get the invite later on you can access that custom data in the invite.extras property. In this example we assume the invite was created with an extras parameter containing {"doc_id": "ab123"}.

In this example the invited user will be added to the list of editors for the document, and then redirected to view that document:

<script type="application/javascript">
  document.addEventListener("UserKitInviteAccepted", function(event) {
    $.post('/accept_invite', {'token': event.detail}, function (response) {
     	// Now that your server has processed the invite, giving the
      // invited user access to the document, redirect them to that
      // document.
      window.location.href = '/doc/' + response['doc_id'];
    }, 'json');
	});
</script>

On your server, setup a request handler for the /accept_invite endpoint. Here you can add the invited user to the list of users who are allowed to edit the document:

import json
import userkit

uk = userkit.UserKit("<YOUR_APP_SECRET_KEY>")

# Portions of following snippet is pseudo code
def accept_invite_handler(request, response):
	json_body = json.loads(request.body)
  
  invite = uk.invites.get_once(json_body['token'])
  if not invite or not invite.accepted:
    # Invite token may be invalid or expired. Abort.
    response.set_status(400)
    return

  # Add the invited user's ID to the list of editors for this
  # document
  doc = get_doc_from_db(invite.extras['doc_id'])
  doc.editors.append(invite.accepted_user)
  doc.save()

  # Return the ID of the document, so your frontend JavaScript
  # code can redirect the user to that document
  json_resp = json.dumps({'doc_id': doc.id})
  response.write(json_resp)

<?php

$uk = new UserKit('<YOUR_APP_SECRET_KEY>');

// Portions of following snippet is pseudo code
function accept_invite_handler($request, $response)
{
  global $uk;
  
  // convert the body response to a json array type 
  $json_body = json_decode($response->body, true);
  
  $invite = $uk->invites->getOnce($json_body['token']);
  if (!$invite || !$invite->accepted)
  {
    // Invite token may be invalid or expired. Abort.
    $response->set_status(400);
    return;
  }

  // Add the invited user's ID to the list of editors for this
  // document
  $doc = get_doc_from_db($invite->extras['doc_id']);
  $doc->editors->append($invite->accepted_user);
  $doc->save();

  // Return the ID of the document, so your frontend JavaScript
  // code can redirect the user to that document
  $json_resp = ['doc_id' => $doc->id];
  $response->write($json_resp);
}