{"_id":"580fd36a02070b3b008c1495","__v":1,"user":"5542d87d795b590d001dc7ff","category":{"_id":"5807813b6d24211900953b99","__v":0,"project":"5589ceae9883a40d00c433f3","version":"5589ceae9883a40d00c433f6","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-10-19T14:20:43.374Z","from_sync":false,"order":3,"slug":"invites","title":"Invites"},"githubsync":"","parentDoc":null,"project":"5589ceae9883a40d00c433f3","version":{"_id":"5589ceae9883a40d00c433f6","__v":10,"project":"5589ceae9883a40d00c433f3","createdAt":"2015-06-23T21:25:02.865Z","releaseDate":"2015-06-23T21:25:02.865Z","categories":["5589ceaf9883a40d00c433f7","559ab19d2100d117005f1269","57d4a754899ab90e00105e5d","5807813b6d24211900953b99","5819154bf62fee0f00949855","5841d27cae05ac2500ba2680","5846c4ee5d064323007b1774","589e29c72793e937001c15c5","5cf0460e272f2c0014a80d17","5cf047bde14258005d7a374e"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-25T21:49:30.247Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":2,"body":"How to create, send, and (optionally) process an invite-accepted event.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Create an Invite\"\n}\n[/block]\nYou 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://api.userkit.io/v1/invites \\\\\\n -u api:<YOUR_APP_SECRET_KEY> \\\\\\n -H \\\"Content-Type: application/json\\\" \\\\\\n -d '{\\\"to_email\\\": \\\"jane.smith:::at:::example.com\\\", \\\"extras\\\": {\\\"doc_id\\\": \\\"ab123\\\"}}'\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"uk = userkit.UserKit(\\\"<YOUR_APP_SECRET_KEY>\\\")\\n\\ninvite = uk.invites.create_invite(to_email=\\\"jane.smith@example.com\\\")\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"<?php\\n\\n$uk = new UserKit('<YOUR_APP_SECRET_KEY>');\\n\\n$invite = $uk->invites->createInvite(['to_email' => 'jane.smith@example.com');\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. Send the invite URL\"\n}\n[/block]\nNow that you've created an invite, you can send the URL stored in `invite.invite_url` by email, SMS, or however you like.\n\nHow 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).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Send an email containing the invite url\\nemail_body = \\\"To join our app click here: {}\\\".format(invite.invite_url)\\nsend_email(to='jane.smith@example.com', body=email_body)\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"<?php\\n\\n// Send an email containing the invite url\\n$email_body = \\\"To join our app click here: $invite->invite_url\\\";\\nsend_email(['to' => 'jane.smith@example.com', 'body' => $email_body);\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nWhen 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).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"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](/docs/quickstart), such as your account page. See the \\\"Widget URL\\\" section in the [dashboard](https://dashboard.userkit.io) under Settings.\"\n}\n[/block]\nIf 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!\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3. Handle invite-accepted callback (optional)\"\n}\n[/block]\nIf 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.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"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\\\"}`.\"\n}\n[/block]\nIn this example the invited user will be added to the list of editors for the document, and then redirected to view that document:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"application/javascript\\\">\\n  UserKitWidget.onInviteAccepted = function(token) {\\n    // POST the invite token to your server (we're using JQuery)\\n    $.post('/accept_invite', {'token': token}, function (response) {\\n     \\t// Now that your server has processed the invite, giving the\\n      // invited user access to the document, redirect them to that\\n      // document.\\n      window.location.href = '/doc/' + response['doc_id'];\\n    }, 'json');\\n  };\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nOn 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import json\\nimport userkit\\n\\nuk = userkit.UserKit(\\\"<YOUR_APP_SECRET_KEY>\\\")\\n\\n# Portions of following snippet is pseudo code\\ndef accept_invite_handler(request, response):\\n\\tjson_body = json.loads(request.body)\\n  \\n  invite = uk.invites.get_once(json_body['token'])\\n  if not invite or not invite.accepted:\\n    # Invite token may be invalid or expired. Abort.\\n    response.set_status(400)\\n    return\\n\\n  # Add the invited user's ID to the list of editors for this\\n  # document\\n  doc = get_doc_from_db(invite.extras['doc_id'])\\n  doc.editors.append(invite.accepted_user)\\n  doc.save()\\n\\n  # Return the ID of the document, so your frontend JavaScript\\n  # code can redirect the user to that document\\n  json_resp = json.dumps({'doc_id': doc.id})\\n  response.write(json_resp) \",\n      \"language\": \"python\",\n      \"name\": null\n    },\n    {\n      \"code\": \"<?php\\n\\n$uk = new UserKit('<YOUR_APP_SECRET_KEY>');\\n\\n// Portions of following snippet is pseudo code\\nfunction accept_invite_handler($request, $response)\\n{\\n  global $uk;\\n  \\n  // convert the body response to a json array type \\n  $json_body = json_decode($response->body, true);\\n  \\n  $invite = $uk->invites->getOnce($json_body['token']);\\n  if (!$invite || !$invite->accepted)\\n  {\\n    // Invite token may be invalid or expired. Abort.\\n    $response->set_status(400);\\n    return;\\n  }\\n\\n  // Add the invited user's ID to the list of editors for this\\n  // document\\n  $doc = get_doc_from_db($invite->extras['doc_id']);\\n  $doc->editors->append($invite->accepted_user);\\n  $doc->save();\\n\\n  // Return the ID of the document, so your frontend JavaScript\\n  // code can redirect the user to that document\\n  $json_resp = ['doc_id' => $doc->id];\\n  $response->write($json_resp);\\n}\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"invites-quickstart","type":"basic","title":"Invites quickstart"}

Overview

Javascript Widget

Server API

Invites

Sending emails

Http-only cookies

Invites quickstart

How to create, send, and (optionally) process an invite-accepted event. [block:api-header] { "type": "basic", "title": "1. Create an Invite" } [/block] 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. [block:code] { "codes": [ { "code": "curl https://api.userkit.io/v1/invites \\\n -u api:<YOUR_APP_SECRET_KEY> \\\n -H \"Content-Type: application/json\" \\\n -d '{\"to_email\": \"jane.smith@example.com\", \"extras\": {\"doc_id\": \"ab123\"}}'", "language": "curl" }, { "code": "uk = userkit.UserKit(\"<YOUR_APP_SECRET_KEY>\")\n\ninvite = uk.invites.create_invite(to_email=\"jane.smith@example.com\")", "language": "python" }, { "code": "<?php\n\n$uk = new UserKit('<YOUR_APP_SECRET_KEY>');\n\n$invite = $uk->invites->createInvite(['to_email' => 'jane.smith@example.com');", "language": "php" } ] } [/block] [block:api-header] { "type": "basic", "title": "2. Send the invite URL" } [/block] 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). [block:code] { "codes": [ { "code": "# Send an email containing the invite url\nemail_body = \"To join our app click here: {}\".format(invite.invite_url)\nsend_email(to='jane.smith@example.com', body=email_body)", "language": "python" }, { "code": "<?php\n\n// Send an email containing the invite url\n$email_body = \"To join our app click here: $invite->invite_url\";\nsend_email(['to' => 'jane.smith@example.com', 'body' => $email_body);", "language": "php" } ] } [/block] 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). [block:callout] { "type": "info", "body": "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](/docs/quickstart), such as your account page. See the \"Widget URL\" section in the [dashboard](https://dashboard.userkit.io) under Settings." } [/block] 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! [block:api-header] { "type": "basic", "title": "3. Handle invite-accepted callback (optional)" } [/block] 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. [block:callout] { "type": "info", "body": "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\"}`." } [/block] In this example the invited user will be added to the list of editors for the document, and then redirected to view that document: [block:code] { "codes": [ { "code": "<script type=\"application/javascript\">\n UserKitWidget.onInviteAccepted = function(token) {\n // POST the invite token to your server (we're using JQuery)\n $.post('/accept_invite', {'token': token}, function (response) {\n \t// Now that your server has processed the invite, giving the\n // invited user access to the document, redirect them to that\n // document.\n window.location.href = '/doc/' + response['doc_id'];\n }, 'json');\n };\n</script>", "language": "html" } ] } [/block] 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: [block:code] { "codes": [ { "code": "import json\nimport userkit\n\nuk = userkit.UserKit(\"<YOUR_APP_SECRET_KEY>\")\n\n# Portions of following snippet is pseudo code\ndef accept_invite_handler(request, response):\n\tjson_body = json.loads(request.body)\n \n invite = uk.invites.get_once(json_body['token'])\n if not invite or not invite.accepted:\n # Invite token may be invalid or expired. Abort.\n response.set_status(400)\n return\n\n # Add the invited user's ID to the list of editors for this\n # document\n doc = get_doc_from_db(invite.extras['doc_id'])\n doc.editors.append(invite.accepted_user)\n doc.save()\n\n # Return the ID of the document, so your frontend JavaScript\n # code can redirect the user to that document\n json_resp = json.dumps({'doc_id': doc.id})\n response.write(json_resp) ", "language": "python", "name": null }, { "code": "<?php\n\n$uk = new UserKit('<YOUR_APP_SECRET_KEY>');\n\n// Portions of following snippet is pseudo code\nfunction accept_invite_handler($request, $response)\n{\n global $uk;\n \n // convert the body response to a json array type \n $json_body = json_decode($response->body, true);\n \n $invite = $uk->invites->getOnce($json_body['token']);\n if (!$invite || !$invite->accepted)\n {\n // Invite token may be invalid or expired. Abort.\n $response->set_status(400);\n return;\n }\n\n // Add the invited user's ID to the list of editors for this\n // document\n $doc = get_doc_from_db($invite->extras['doc_id']);\n $doc->editors->append($invite->accepted_user);\n $doc->save();\n\n // Return the ID of the document, so your frontend JavaScript\n // code can redirect the user to that document\n $json_resp = ['doc_id' => $doc->id];\n $response->write($json_resp);\n}", "language": "php" } ] } [/block]