{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"params":[],"settings":""},"next":{"description":"","pages":[]},"title":"Invites quickstart","type":"basic","slug":"invites-quickstart","excerpt":"","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=\\\"[email protected]\\\")\",\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' => '[email protected]');\",\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='[email protected]', 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' => '[email protected]', '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 document.addEventListener(\\\"UserKitInviteAccepted\\\", function(event) {\\n $.post('/accept_invite', {'token': event.detail}, 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\\t});\\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]","updates":[],"order":2,"isReference":true,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"580fd36a02070b3b008c1495","__v":1,"createdAt":"2016-10-25T21:49:30.247Z","user":"5542d87d795b590d001dc7ff","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Invites","slug":"invites","order":3,"from_sync":false,"reference":true,"_id":"5807813b6d24211900953b99","__v":0,"project":"5589ceae9883a40d00c433f3","version":"5589ceae9883a40d00c433f6","createdAt":"2016-10-19T14:20:43.374Z"},"githubsync":"","parentDoc":null,"project":"5589ceae9883a40d00c433f3","version":{"version":"1.0","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":true,"is_hidden":false,"is_deprecated":false,"categories":["5589ceaf9883a40d00c433f7","559ab19d2100d117005f1269","57d4a754899ab90e00105e5d","5807813b6d24211900953b99","5819154bf62fee0f00949855","5841d27cae05ac2500ba2680","5846c4ee5d064323007b1774","589e29c72793e937001c15c5","5cf0460e272f2c0014a80d17","5cf047bde14258005d7a374e","5db6fa2c7f86fa004ff2c35b","5e349a6a02520b006458b0ae","5e4c89eafd907100654072f2","5e4d7a1feca7f90018b15b9b","5e4eff0ec3399b005118d83a"],"_id":"5589ceae9883a40d00c433f6","releaseDate":"2015-06-23T21:25:02.865Z","__v":15,"createdAt":"2015-06-23T21:25:02.865Z","project":"5589ceae9883a40d00c433f3"}}