{"_id":"59f79e3c584eb200345cecc5","project":"59f79e3c584eb200345ceafc","__v":0,"initVersion":null,"user":{"_id":"54e4044e8ef7552300409dcb","username":"","name":"Sankaet Pathak"},"createdAt":"2015-05-19T21:42:06.950Z","changelog":[],"body":"Recently we had a few of our merchants ask for some advice around the best practices for authentication with SynapsePay, so we thought we would write this post describing some options for you  (i.e. **OAuth vs. Login vs. Force Create**)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1) OAuth 2.0\"\n}\n[/block]\nThis is the standard OAuth 2.0 protocol used for creating and authenticating users.\n\nFirst, you create a user (**user/create**), you will get **oauth_consumer_key**, **refresh_token** and **expires_in** . You will be able to use the **oauth_consumer_key** to make payments and perform actions on behalf of the customer. When the **oauth_consumer_key** expires, you can use the **refresh_token** to refresh access to that account again (i.e. don't forget to store **refresh_token**).\n\nSteps to Authenticate:\n\n**Step 1:  Send user/create payload**\n**Example user/create payload:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"## Post this to user/create\\n\\npayload = {\\n  \\n\\t\\\"email\\\":\\\"[email protected]\\\",\\n  \\\"fullname\\\":\\\"Jon Doe\\\",\\n  \\\"phonenumber\\\":\\\"901-111-1111\\\",\\n  \\\"ip_address\\\":\\\"111.11.111\\\",\\n  \\\"client_id\\\":\\\"your_client_id\\\",\\n  \\\"client_secret\\\":\\\"your_client_secret\\\"\\n  \\n}\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n**Step 2:  Store response (key + token + expiration)** \nWhen you send the user/create payload, a user is created and we'll send you **username**, **oauth_consumer_key**, **refresh_token** and **expires_in**.\n\nStore **oauth_consumer_key** , **refresh_token** and ** expires_in** into your database. Next time when you would want to gain access to this user, it will come in handy.\n\nNote:  **expires_in** signifies the time (in seconds) it will take for the **oauth_consumer_key** to expire. \n\nOnce you have stored this information, you can use the returned **oauth_consumer_key** for the rest of the operations.\n\n**Step 3:  Regaining access via user/refresh**\nAt some point ether your **oauth_consumer_key** will expire or you will loose access to it, then you would need to regain access to the customer's account by using the **user/refresh** protocol by supplying the **refresh_token**.\n\n**Example user/refresh payload:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"## Post this to user/refresh\\n\\npayload = {\\n  \\n  \\\"refresh_token\\\":\\\"cutomer_refresh_token\\\",\\n  \\\"client_id\\\":\\\"your_client_id\\\",\\n  \\\"client_secret\\\":\\\"your_client_secret\\\"\\n  \\n}\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n**Wolla!!** This will get you access to the account again, and you will get a new **oauth_consumer_key** and **refresh_token** to use later (**read:  store it**)\n\n**Advantages to this approach:**\n* Uses a familiar OAuth 2.0 approach\n* Arguably more secure than login protocol given it expires\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2) Login Protocol\"\n}\n[/block]\nThink of the protocol as an alternative to OAuth that lets you mimic a user creating account in your system on SynapsePay by creating an account to send payments, then logging into their account to perform your desired tasks.\n\nSteps to Authenticate:\n\n**Step 1:  Send user/create payload**\n**Example user/create payload:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"## Post this to user/create\\n\\npayload = {\\n  \\n\\t\\\"email\\\":\\\"[email protected]\\\",\\n  \\\"fullname\\\":\\\"Jon Doe\\\",\\n  \\\"phonenumber\\\":\\\"901-111-1111\\\",\\n  \\\"ip_address\\\":\\\"111.11.111\\\",\\n  \\\"password\\\":\\\"testPassword\\\", ## in this case specify the password for user\\n  \\\"client_id\\\":\\\"your_client_id\\\",\\n  \\\"client_secret\\\":\\\"your_client_secret\\\"\\n  \\n}\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n**Step 2:  Store response (username + password)** \nWhen you send the user/create payload, a user is created and we'll send you back the **username**.\n\nStore that **username** and **password** that you specified into your database. Next time you want to gain access to this user, it will come in handy.\n\n**Step 3:  Regaining access via user/login**\nOnce you have stored the information in Step 2, you can supply the information to **user/login** then use the returned **oauth_consumer_key** for the rest of the operations.\n\nWhen your **oauth_consumer_key** expires or you will loose access to it, then you would need to regain access to the user's account by supplying the **username** and **password** to **user/login**.\n\n**Example user/login payload:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"## Post this to user/login\\n\\npayload = {\\n  \\n\\t\\\"username\\\":\\\"username\\\",\\n  \\\"password\\\":\\\"password\\\",\\n  \\\"client_id\\\":\\\"your_client_id\\\",\\n  \\\"client_secret\\\":\\\"your_client_secret\\\"\\n  \\n}\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThis will get you access to the account again and respond with a new **oauth_consumer_key** to perform functions with the user.\n\n**Advantages to this approach:**\n* Uses a traditional login protocol familiar to users/developers\n* No need to worry about handling token expiration\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3) Force_Create --> \\\"NO\\\"\"\n}\n[/block]\nThis protocol is meant for developers who want a more loosely coupled solution. It lets you skip both OAuth protocol and Login Protocol.\n\nJust use **user/create** every-time to get **oauth_consumer_key** and we'll handle the rest. The system automatically creates a customer when the customer wasn't created.  However, if the customer was previously created under your sandbox, it will refresh your access and spit out a new **oauth_consumer_key**.\n\nSteps to Authenticate:\n\n**Step 1:  Send user/create payload**\n**Example user/create payload:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"## Post this to user/create\\n\\npayload = {\\n  \\n\\t\\\"email\\\":\\\"[email protected]\\\",\\n  \\\"fullname\\\":\\\"Jon Doe\\\",\\n  \\\"phonenumber\\\":\\\"901-111-1111\\\",\\n  \\\"ip_address\\\":\\\"111.11.111\\\",\\n  \\\"force_create\\\":\\\"no\\\", ## in this case specify force_create as \\\"no\\\"\\n  \\\"client_id\\\":\\\"your_client_id\\\",\\n  \\\"client_secret\\\":\\\"your_client_secret\\\"\\n  \\n}\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThis will give you **oauth_consumer_key** for the customer each time.\n\n**Advantages to this approach:**\n\n* Quick to implement\n* No need to store Synapse specified **usernames**, **oauth_consumer_keys** or **refresh_keys**","slug":"best-authentication-practices-with-synapsepay","title":"Best Practices: Authentication"}

Best Practices: Authentication


Recently we had a few of our merchants ask for some advice around the best practices for authentication with SynapsePay, so we thought we would write this post describing some options for you (i.e. **OAuth vs. Login vs. Force Create**) [block:api-header] { "type": "basic", "title": "1) OAuth 2.0" } [/block] This is the standard OAuth 2.0 protocol used for creating and authenticating users. First, you create a user (**user/create**), you will get **oauth_consumer_key**, **refresh_token** and **expires_in** . You will be able to use the **oauth_consumer_key** to make payments and perform actions on behalf of the customer. When the **oauth_consumer_key** expires, you can use the **refresh_token** to refresh access to that account again (i.e. don't forget to store **refresh_token**). Steps to Authenticate: **Step 1: Send user/create payload** **Example user/create payload:** [block:code] { "codes": [ { "code": "## Post this to user/create\n\npayload = {\n \n\t\"email\":\"[email protected]\",\n \"fullname\":\"Jon Doe\",\n \"phonenumber\":\"901-111-1111\",\n \"ip_address\":\"111.11.111\",\n \"client_id\":\"your_client_id\",\n \"client_secret\":\"your_client_secret\"\n \n}", "language": "python" } ] } [/block] **Step 2: Store response (key + token + expiration)** When you send the user/create payload, a user is created and we'll send you **username**, **oauth_consumer_key**, **refresh_token** and **expires_in**. Store **oauth_consumer_key** , **refresh_token** and ** expires_in** into your database. Next time when you would want to gain access to this user, it will come in handy. Note: **expires_in** signifies the time (in seconds) it will take for the **oauth_consumer_key** to expire. Once you have stored this information, you can use the returned **oauth_consumer_key** for the rest of the operations. **Step 3: Regaining access via user/refresh** At some point ether your **oauth_consumer_key** will expire or you will loose access to it, then you would need to regain access to the customer's account by using the **user/refresh** protocol by supplying the **refresh_token**. **Example user/refresh payload:** [block:code] { "codes": [ { "code": "## Post this to user/refresh\n\npayload = {\n \n \"refresh_token\":\"cutomer_refresh_token\",\n \"client_id\":\"your_client_id\",\n \"client_secret\":\"your_client_secret\"\n \n}", "language": "python" } ] } [/block] **Wolla!!** This will get you access to the account again, and you will get a new **oauth_consumer_key** and **refresh_token** to use later (**read: store it**) **Advantages to this approach:** * Uses a familiar OAuth 2.0 approach * Arguably more secure than login protocol given it expires [block:api-header] { "type": "basic", "title": "2) Login Protocol" } [/block] Think of the protocol as an alternative to OAuth that lets you mimic a user creating account in your system on SynapsePay by creating an account to send payments, then logging into their account to perform your desired tasks. Steps to Authenticate: **Step 1: Send user/create payload** **Example user/create payload:** [block:code] { "codes": [ { "code": "## Post this to user/create\n\npayload = {\n \n\t\"email\":\"[email protected]\",\n \"fullname\":\"Jon Doe\",\n \"phonenumber\":\"901-111-1111\",\n \"ip_address\":\"111.11.111\",\n \"password\":\"testPassword\", ## in this case specify the password for user\n \"client_id\":\"your_client_id\",\n \"client_secret\":\"your_client_secret\"\n \n}", "language": "python" } ] } [/block] **Step 2: Store response (username + password)** When you send the user/create payload, a user is created and we'll send you back the **username**. Store that **username** and **password** that you specified into your database. Next time you want to gain access to this user, it will come in handy. **Step 3: Regaining access via user/login** Once you have stored the information in Step 2, you can supply the information to **user/login** then use the returned **oauth_consumer_key** for the rest of the operations. When your **oauth_consumer_key** expires or you will loose access to it, then you would need to regain access to the user's account by supplying the **username** and **password** to **user/login**. **Example user/login payload:** [block:code] { "codes": [ { "code": "## Post this to user/login\n\npayload = {\n \n\t\"username\":\"username\",\n \"password\":\"password\",\n \"client_id\":\"your_client_id\",\n \"client_secret\":\"your_client_secret\"\n \n}", "language": "python" } ] } [/block] This will get you access to the account again and respond with a new **oauth_consumer_key** to perform functions with the user. **Advantages to this approach:** * Uses a traditional login protocol familiar to users/developers * No need to worry about handling token expiration [block:api-header] { "type": "basic", "title": "3) Force_Create --> \"NO\"" } [/block] This protocol is meant for developers who want a more loosely coupled solution. It lets you skip both OAuth protocol and Login Protocol. Just use **user/create** every-time to get **oauth_consumer_key** and we'll handle the rest. The system automatically creates a customer when the customer wasn't created. However, if the customer was previously created under your sandbox, it will refresh your access and spit out a new **oauth_consumer_key**. Steps to Authenticate: **Step 1: Send user/create payload** **Example user/create payload:** [block:code] { "codes": [ { "code": "## Post this to user/create\n\npayload = {\n \n\t\"email\":\"[email protected]\",\n \"fullname\":\"Jon Doe\",\n \"phonenumber\":\"901-111-1111\",\n \"ip_address\":\"111.11.111\",\n \"force_create\":\"no\", ## in this case specify force_create as \"no\"\n \"client_id\":\"your_client_id\",\n \"client_secret\":\"your_client_secret\"\n \n}", "language": "python" } ] } [/block] This will give you **oauth_consumer_key** for the customer each time. **Advantages to this approach:** * Quick to implement * No need to store Synapse specified **usernames**, **oauth_consumer_keys** or **refresh_keys**