{"_id":"55a9671d4c661b3700cf4e79","category":{"_id":"53ff9e3723a37e1d5cebaff7","project":"53fe6dc5addab8973c1af267","__v":5,"pages":["53fe6dc5addab8973c1af26d","53ff992a23a37e1d5cebafdb","53fe746baddab8973c1af286","53ff9e2223a37e1d5cebaff5","55a9671d4c661b3700cf4e79","5614781f91fe0f1900927445","56183be0a410c90d00c61408","562586b423053b2300f5972e","564ba9403025942100a8e708"],"version":"53fe6dc5addab8973c1af26a","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-08-28T21:25:11.124Z","from_sync":false,"order":0,"slug":"hello","title":"Hello!"},"parentDoc":null,"project":"53fe6dc5addab8973c1af267","user":"53fe6d8baddab8973c1af266","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"},"__v":2,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-07-17T20:35:41.663Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"To make sure that your users have a great experience logging in with Clef, make sure you’ve done everything on this list. All of these are requirements to make Clef safe and easy, so we do not support integrations that do not follow these guidelines. Integrations that do not follow them may lose API access and will be unable to offer Clef. \n\n# I. Use the Clef ID to identify users \n\nEvery time a user logs in with Clef, you’ll get their unique Clef ID in the response. These IDs are constant and specific to your integration, so they should be stored in your database and used to look the user back up when they log in. You can also request other information like the user’s email address or phone number from Clef, but the user can change this information in their Clef account so you shouldn’t use it to identify them. \n\n# II. Make sure users can register with Clef\n\nClef will help new users find your site, but they’ll only try it out if they can sign up for your service. You should include the Clef button on your registration page, and when a user with a new Clef ID logs into your site, you should begin the registration process for them. For most integrations, this will just mean using the information you get from the Clef API to create a new account and log the user in (magic!), but if you have complex registration requirements, you should use Clef to complete as much of it as possible, and then let the user complete the rest of the registration process from there. \n\n# III. Logout with Clef should work seamlessly\n\nWhen a user logs out of Clef, they should immediately be logged out of your site. This is done with the Logout Hook, which is quick to implement and critical for user security. The logout can happen on the next page refresh, or immediately using a service like [Pusher](http://pusher.com), so that the user is unauthenticated and redirected to the appropriate page.\n\n# IV. Clef should never be used on top of passwords\n\nClef is two-factor authentication all by itself, adding passwords on top makes it unnecessarily more difficult and guarantees that fewer users will log in and get the extra protection.\n\n# V. Existing users should be able to connect Clef to their account\n\nIf a Clef user logs in with an email or phone number that you already have on file, you should recognize that they are the same person and let them connect Clef to their old account. After they’ve logged in with Clef, they should be redirected to a screen where they can input their old username and password to confirm ownership of that account, and then the Clef ID should be attached to that account. Users should also be able to enable Clef from the settings when they are logged in. \n\n# VI. Clef users should have passwords disabled by default\n\nAn account is only as safe as the weakest point of entry, so leaving passwords on by default means that users won’t actually get any extra protection from using Clef. Make sure that once a user starts using Clef, logging in with passwords is automatically disabled. \n\n# VII. Implement the state parameter in the OAuth handshake\n\nThe state parameter is sometimes viewed as optional for OAuth handshakes, but it’s critical for keeping logins on your site secure. You can see how to implement the state parameter [here](doc:verifying-state-parameter) .","excerpt":"Follow these guidelines to ensure your Clef integration works well for you and your users.","slug":"integration-guidelines","type":"basic","title":"Integration Requirements"}

Integration Requirements

Follow these guidelines to ensure your Clef integration works well for you and your users.

To make sure that your users have a great experience logging in with Clef, make sure you’ve done everything on this list. All of these are requirements to make Clef safe and easy, so we do not support integrations that do not follow these guidelines. Integrations that do not follow them may lose API access and will be unable to offer Clef. # I. Use the Clef ID to identify users Every time a user logs in with Clef, you’ll get their unique Clef ID in the response. These IDs are constant and specific to your integration, so they should be stored in your database and used to look the user back up when they log in. You can also request other information like the user’s email address or phone number from Clef, but the user can change this information in their Clef account so you shouldn’t use it to identify them. # II. Make sure users can register with Clef Clef will help new users find your site, but they’ll only try it out if they can sign up for your service. You should include the Clef button on your registration page, and when a user with a new Clef ID logs into your site, you should begin the registration process for them. For most integrations, this will just mean using the information you get from the Clef API to create a new account and log the user in (magic!), but if you have complex registration requirements, you should use Clef to complete as much of it as possible, and then let the user complete the rest of the registration process from there. # III. Logout with Clef should work seamlessly When a user logs out of Clef, they should immediately be logged out of your site. This is done with the Logout Hook, which is quick to implement and critical for user security. The logout can happen on the next page refresh, or immediately using a service like [Pusher](http://pusher.com), so that the user is unauthenticated and redirected to the appropriate page. # IV. Clef should never be used on top of passwords Clef is two-factor authentication all by itself, adding passwords on top makes it unnecessarily more difficult and guarantees that fewer users will log in and get the extra protection. # V. Existing users should be able to connect Clef to their account If a Clef user logs in with an email or phone number that you already have on file, you should recognize that they are the same person and let them connect Clef to their old account. After they’ve logged in with Clef, they should be redirected to a screen where they can input their old username and password to confirm ownership of that account, and then the Clef ID should be attached to that account. Users should also be able to enable Clef from the settings when they are logged in. # VI. Clef users should have passwords disabled by default An account is only as safe as the weakest point of entry, so leaving passwords on by default means that users won’t actually get any extra protection from using Clef. Make sure that once a user starts using Clef, logging in with passwords is automatically disabled. # VII. Implement the state parameter in the OAuth handshake The state parameter is sometimes viewed as optional for OAuth handshakes, but it’s critical for keeping logins on your site secure. You can see how to implement the state parameter [here](doc:verifying-state-parameter) .