{"_id":"5702e319747d6d0e0077002e","__v":12,"user":"56b8f6ad43bbd10d0081d1f0","parentDoc":null,"category":{"_id":"5702e2d2f2d6f336005e901f","__v":0,"version":"53fe6dc5addab8973c1af26a","project":"53fe6dc5addab8973c1af267","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-04T21:55:30.420Z","from_sync":false,"order":9,"slug":"distributed-authentication","title":"Distributed Authentication"},"project":"53fe6dc5addab8973c1af267","version":{"_id":"53fe6dc5addab8973c1af26a","__v":19,"project":"53fe6dc5addab8973c1af267","createdAt":"2014-08-27T23:46:13.941Z","releaseDate":"2014-08-27T23:46:13.941Z","categories":["53fe6dc5addab8973c1af26b","53fe71a2addab8973c1af276","53fe7d89addab8973c1af2b0","53fe7d8daddab8973c1af2b1","53fe836faddab8973c1af2ce","53ff9a4823a37e1d5cebafe1","53ff9e3723a37e1d5cebaff7","53ffaca523a37e1d5cebb039","53ffad2e23a37e1d5cebb03c","5400c7d2ec93b29b61d4f7be","5400f0e1ec93b29b61d4f7dd","54d5636323010a0d001aca81","54d565c1276f8e0d00feab54","54ff40532882a10d00546927","556606d25561af0d008208b7","558c91900b236c2500d37c9a","56180a14f8c9632100ac7599","564fb3a59b4fab1700187518","5702e2d2f2d6f336005e901f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["5702e6ff18ad001700a29553"],"next":{"pages":[],"description":""},"createdAt":"2016-04-04T21:56:41.356Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Sending a confirmable request requires the delivery of a payload to our action confirmation endpoint, `/api/v1/validate`. The payload that’s intended to trigger a confirmation request on the user’s device should have the following *required* keys:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Key Name\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`nonce`\",\n    \"0-1\": \"A one-time value that you’d associate (and store) with this payload.\",\n    \"1-0\": \"`description`\",\n    \"1-1\": \"The expected description that the user sees when this request is sent.\",\n    \"2-0\": \"`type`\",\n    \"2-1\": \"The kind of action you're using for this request.\",\n    \"3-1\": \"The URI to navigate to with the response of the user’s confirmation (or lack thereof).\",\n    \"3-0\": \"`redirect_url`\",\n    \"4-0\": \"`clef_id`\",\n    \"4-1\": \"The user ID that Clef provides you in relation to the user.\",\n    \"5-0\": \"`session_id`\",\n    \"5-1\": \"The current session in which this user is authenticated within.\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\nThe resulting body should look something like this (in PHP):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$payload = {\\n  \\\"nonce\\\": bin2hex(openssl_random_pseudo_bytes(16)),\\n  \\\"clef_id\\\": $clef_id,\\n  \\\"redirect_url\\\": “http://magic.school/bus/verify”,\\n  \\\"session_id\\\": “ClEf312”,\\n  \\\"type\\\": \\\"withdrawal\\\",\\n  \\\"description\\\": \\\"You requested to withdraw 5 BTC from your wallet.\\\"\\n};\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nOnce you have this payload object, you’ll want to do the following:\n\n  * Make it into a string.\n  * Sign it using your application’s private key.\n  * Encode said message.\n\nThe above would look like the following using the Clef PHP library:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$signed_payload = \\\\Clef\\\\Clef::sign_custom_payload($payload);\\n$encoded_payload = \\\\Clef\\\\Clef::encode_payload($signed_payload));\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]\nFrom there, you’ll want to redirect the user to the `/validate` API endpoint; we’ll handle the rest.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Only Supported In Our PHP Library\",\n  \"body\": \"Currently, only our PHP library has out-of-the-box support for withdrawal confirmations. Check it out on [Github](https://github.com/clef/clef-php/tree/custom-actions#constructing-a-custom-payload).\"\n}\n[/block]","excerpt":"Make sure your users really want to do that action they requested!","slug":"sending-confirmable-requests","type":"basic","title":"Sending Confirmable Requests"}

Sending Confirmable Requests

Make sure your users really want to do that action they requested!

Sending a confirmable request requires the delivery of a payload to our action confirmation endpoint, `/api/v1/validate`. The payload that’s intended to trigger a confirmation request on the user’s device should have the following *required* keys: [block:parameters] { "data": { "h-0": "Key Name", "h-1": "Description", "0-0": "`nonce`", "0-1": "A one-time value that you’d associate (and store) with this payload.", "1-0": "`description`", "1-1": "The expected description that the user sees when this request is sent.", "2-0": "`type`", "2-1": "The kind of action you're using for this request.", "3-1": "The URI to navigate to with the response of the user’s confirmation (or lack thereof).", "3-0": "`redirect_url`", "4-0": "`clef_id`", "4-1": "The user ID that Clef provides you in relation to the user.", "5-0": "`session_id`", "5-1": "The current session in which this user is authenticated within." }, "cols": 2, "rows": 6 } [/block] The resulting body should look something like this (in PHP): [block:code] { "codes": [ { "code": "$payload = {\n \"nonce\": bin2hex(openssl_random_pseudo_bytes(16)),\n \"clef_id\": $clef_id,\n \"redirect_url\": “http://magic.school/bus/verify”,\n \"session_id\": “ClEf312”,\n \"type\": \"withdrawal\",\n \"description\": \"You requested to withdraw 5 BTC from your wallet.\"\n};", "language": "php" } ] } [/block] Once you have this payload object, you’ll want to do the following: * Make it into a string. * Sign it using your application’s private key. * Encode said message. The above would look like the following using the Clef PHP library: [block:code] { "codes": [ { "code": "$signed_payload = \\Clef\\Clef::sign_custom_payload($payload);\n$encoded_payload = \\Clef\\Clef::encode_payload($signed_payload));", "language": "php" } ] } [/block] From there, you’ll want to redirect the user to the `/validate` API endpoint; we’ll handle the rest. [block:callout] { "type": "warning", "title": "Only Supported In Our PHP Library", "body": "Currently, only our PHP library has out-of-the-box support for withdrawal confirmations. Check it out on [Github](https://github.com/clef/clef-php/tree/custom-actions#constructing-a-custom-payload)." } [/block]