{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"params":[],"method":"get"},"next":{"description":"Check out the API Reference to learn more about how to use our API","pages":[{"type":"url","icon":"file-text-o","name":"API Reference","value":"https://docs.apruve.com/reference"}]},"title":"OAuth 2.0 for API requests","type":"basic","slug":"oauth2","excerpt":"","body":"[block:api-header]\n{\n  \"title\": \"Overview\"\n}\n[/block]\nWhen you set up your store to use OAuth, customers will only need to sign in with Apruve once. You would be able to provide a link for them to sign in and authorize you the merchant to place orders on their behalf. If they accept, you will receive a token that can be used to send orders to Apruve through our API without popping up our checkout modal. This provides a more streamlined and integrated purchasing experience for your customers. \n[block:api-header]\n{\n  \"title\": \"Merchant settings for OAuth\"\n}\n[/block]\nTo enable single sign-on for your store, sign in to your Apruve dashboard, click the **Settings** link on the side bar and select **Technical**. On this page, find the **OAuth** section where you will be able to enter your **Redirect URI** and generate an OAuth client by clicking **Create Client**.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6f6570e-redirect_set_light_marked.png\",\n        \"redirect_set_light marked.png\",\n        2510,\n        1812,\n        \"#c7dbdc\"\n      ],\n      \"sizing\": \"smart\"\n    }\n  ]\n}\n[/block]\nAfter creating the OAuth client, you will see a Client ID and Secret.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e6c488c-with_keys_light.png\",\n        \"with_keys_light.png\",\n        2510,\n        1812,\n        \"#c6dbdc\"\n      ],\n      \"sizing\": \"smart\"\n    }\n  ]\n}\n[/block]\nTo disable OAuth single sign-on, click the Revoke button. You will no longer be able to place orders on your customers' behalf using OAuth tokens and will not be able to authorize new tokens.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Important!\",\n  \"body\": \"If you disable OAuth, make sure you really mean it! If you re-enable it, you will get new Client ID and Secret values and will need to update your integration with the new values. Also, any customers that had previously authorized will need to re-authorize.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Authorization grant flow\"\n}\n[/block]\nNow that you have the OAuth client set up, you can start the authorization grant flow for a customer. First, the customer must initiate a GET request to the authorization endpoint in Apruve. This is done by having them follow a link that you generate. The link will have the following format:\n\n`https://test.apruve.com/oauth2/authorize` in the test environment, and \n`https://app.apruve.com/oauth2/authorize` in production. \n\nThe url must also have the following query parameters.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Request query parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"client_id\",\n    \"0-1\": \"The Client ID is provided when you generated the OAuth client in the first step.\",\n    \"1-0\": \"redirect_uri\",\n    \"1-1\": \"The Redirect URL you provided when generating the OAuth client in the first step. This is where the customer will be redirected to when the grant flow is complete.\",\n    \"2-0\": \"response_type\",\n    \"2-1\": \"The value for this is always `code`\",\n    \"3-0\": \"state\",\n    \"3-1\": \"An **optional** value that you can provide that we will include in the query parameters when redirecting the user to `redirect_uri` after the grant flow is complete.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nExample Authorization URL\n`https://test.apruve.com/oauth2/authorize?client_id=5fd4dc5ce8c2d76f817c0b7b98d5fc0b3e06384b83fa7f2fdfe1f962bf92093a&redirect_uri=https%3A%2F%2Fspacelysprockets.com%2Foauth_callback&response_type=code&state=fa0424cef2f9350a6a53deb6baeed643c0a82365d1132113450e53e51f063103`\n\nFor the following values:\nclient_id: 5fd4dc5ce8c2d76f817c0b7b98d5fc0b3e06384b83fa7f2fdfe1f962bf92093a\nredirect_uri: https://spacelysprockets.com/oauth_callback\nstate: fa0424cef2f9350a6a53deb6baeed643c0a82365d1132113450e53e51f063103\nresponse_type: code\n\nThis will prompt your customer to log into Apruve, after which we will show a page with options to **Authorize** or **Cancel** the request.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f7673da-authorize_light.png\",\n        \"authorize_light.png\",\n        2510,\n        1812,\n        \"#f8f9f9\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Redirect back to your site\"\n}\n[/block]\nThe customer can select to **Cancel** or **Authorize** your request to operate on their behalf. In either case, we will send the client back to the `Redirect URI` the you initially provided and have used as a query parameter in the last step. We will use the following query parameters in this step.\n\n#### Redirect From Apruve\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"code\",\n    \"1-0\": \"state\",\n    \"0-1\": \"A randomly generated code used for the next step. This will not be provided if the customer declined authorization.\",\n    \"2-0\": \"error\",\n    \"3-0\": \"error_description\",\n    \"3-1\": \"Description of error, only provided if there was an error.\",\n    \"1-1\": \"The optional state that you provided in the previous step. Use this to prevent cross-site request forgery attacks.\",\n    \"2-1\": \"An error code that is only provided if there was an error or the customer declined authorization\",\n    \"h-1\": \"Description\",\n    \"h-0\": \"Request query parameter\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nExample (success): `https://spacelysprockets.com/oauth_callback/?code=5559c688c82f17c0966afebaf07eb6889e758810793b8c9fa5b7e7b1372f2ae6&state=fa0424cef2f9350a6a53deb6baeed643c0a82365d1132113450e53e51f063103`\n\nExample (error): `https://spacelysprockets.com/oauth_callback/?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&state=fa0424cef2f9350a6a53deb6baeed643c0a82365d1132113450e53e51f063103`\n\n[block:api-header]\n{\n  \"title\": \"Request the token\"\n}\n[/block]\nThe final step is to send a request for the access token. In this step you will POST to the following url:\n\n`https://test.apruve.com/oauth2/token` for the test environment and \n`https://app.apruve.com/oauth2/token` for production.\n\nThe request must have the following parameters:\n[block:parameters]\n{\n  \"data\": {\n    \"2-0\": \"code\",\n    \"2-1\": \"The code we provide to you as a query parameter in the redirect.\",\n    \"3-0\": \"grant_type\",\n    \"3-1\": \"This will always be `authorization_code`.\",\n    \"4-0\": \"redirect_uri\",\n    \"4-1\": \"The redirect uri that you provided when generating the client and that has been used in each of the previous steps.\",\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"5-0\": \"state\",\n    \"5-1\": \"The optional state that you provided in the previous step. Use this to prevent cross-site request forgery attacks.\",\n    \"0-0\": \"client_id\",\n    \"0-1\": \"The client ID we provided when you generated the OAuth client in the first step.\",\n    \"1-0\": \"client_secret\",\n    \"1-1\": \"The secret we provided when you generated the OAuth client in the first step.\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\nIf everything is successful, our response payload will contain the following data, which should be stored with the associated user in your system as they will be required to make requests on their behalf.\n\n#### Response From Apruve \n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"token\",\n    \"0-1\": \"Access token used to authorize requests on behalf of your customer. This lasts for 120 min, before you need to use the refresh token to obtain a new one\",\n    \"1-0\": \"refresh_token\",\n    \"1-1\": \"Token used to obtain a new access token when it expires\",\n    \"3-0\": \"corporate_account_id\",\n    \"3-1\": \"The ID of your customer's corporate account in Apruve. This refers to the company that the user belongs to as opposed to the user itself.\",\n    \"h-0\": \"Response Parameter\",\n    \"h-1\": \"Description\",\n    \"2-1\": \"The amount of time in seconds that the new access token will be valid before expiring.\",\n    \"2-0\": \"expires_in\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Refreshing the token\"\n}\n[/block]\nWhen the access token expires after 120 minutes, you need to obtain a new one using the refresh token. To do so, make a post to the same endpoint used to get the token originally, this time using the following parameters:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"client_id\",\n    \"0-1\": \"The client ID we provided when you generated the OAuth client in the first step.\",\n    \"1-1\": \"The secret we provided when you generated the OAuth client in the first step.\",\n    \"1-0\": \"client_secret\",\n    \"2-0\": \"refresh_token\",\n    \"3-1\": \"This will always be `refresh_token`.\",\n    \"3-0\": \"grant_type\",\n    \"2-1\": \"The last `refresh_token` that you've received for this user.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\nIf everything is successful, our response payload will contain the following data. The new `refresh_token` and `access_token` should be stored with the associated user in your system.\n#### Refresh Token Response From Apruve \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Response Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"access_token\",\n    \"0-1\": \"A new access token for this user\",\n    \"1-0\": \"expires_in\",\n    \"1-1\": \"The amount of time in seconds that the new access token will be valid before expiring.\",\n    \"2-0\": \"refresh_token\",\n    \"2-1\": \"A new refresh token for this user\",\n    \"3-1\": \"The ID of your customer's corporate account in Apruve. This refers to the company that the user belongs to as opposed to the user itself.\",\n    \"3-0\": \"corporate_account_id\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Using the access token in requests\"\n}\n[/block]\nWith the user's access token you can create orders on their behalf and get data about their account such as credit limit. In order to use the access token, you must put it in an Authorization header when making requests. For example:\n\n`Authorization: Bearer d068492b812fb8d94b0d824627cf27f4ae5e3a45fd7302537fe5fa060c44a550`\n\nIf you get a 401 response code with the following error payload, it is time to request another access token, follow the previous step. You can also keep track of the expiration times on your end.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"message\\\": \\\"Invalid authentication token.\\\"\\n  }\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","updates":[],"order":7,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"59fa4f125a3c4e00101b9925","project":"58b9e955fba7da250056ff86","version":{"version":"4.0","version_clean":"4.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["58b9e955fba7da250056ff8a","58b9e9e168a4a5190011dcc2","58b9ea1de87271190074c623","58b9f9df4022e60f00ae20af","58bda4f77181082500275455","58bda69b8bcd092f00e52862","58bda751b4e9640f00e4bdaf","58e800fabc0deb0f002801f3","5925bfd9504e5239003807f4","5925c026aef9fd27008525c0","5925c0e7dd71b51b00ccc329","592d872451a3e80f00eb4a1a","592d9539b9b6b91900569ea0","592d990a51a3e80f00eb4c25","592d9bf480832f0f00ddfa46","592d9d5051a3e80f00eb4e02","592dbd5cd97832190073d76a","598360d76050430034ef4e07","598363237c926c0028d2e420","598363755de0a1002049efad","598363c27c926c0028d2e442","59c15f2ebc639a0032f770f0"],"_id":"58b9e955fba7da250056ff89","releaseDate":"2017-03-03T22:08:21.880Z","__v":22,"createdAt":"2017-03-03T22:08:21.880Z","project":"58b9e955fba7da250056ff86"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Developer Resources","slug":"developer-resources-1","order":2,"from_sync":false,"reference":false,"_id":"598360d76050430034ef4e07","project":"58b9e955fba7da250056ff86","version":"58b9e955fba7da250056ff89","isAPI":false,"createdAt":"2017-08-03T17:43:51.991Z","__v":0},"user":"59232ee4e465c11900921e8a","createdAt":"2017-11-01T22:47:46.318Z","githubsync":"","__v":1,"parentDoc":null,"updatedAt":"2020-09-11T15:04:54.437Z","pendingAlgoliaPublish":false,"previousSlug":"oauth-single-sign-on","slugUpdatedAt":"2020-09-11T15:16:03.940Z"}

OAuth 2.0 for API requests


[block:api-header] { "title": "Overview" } [/block] When you set up your store to use OAuth, customers will only need to sign in with Apruve once. You would be able to provide a link for them to sign in and authorize you the merchant to place orders on their behalf. If they accept, you will receive a token that can be used to send orders to Apruve through our API without popping up our checkout modal. This provides a more streamlined and integrated purchasing experience for your customers. [block:api-header] { "title": "Merchant settings for OAuth" } [/block] To enable single sign-on for your store, sign in to your Apruve dashboard, click the **Settings** link on the side bar and select **Technical**. On this page, find the **OAuth** section where you will be able to enter your **Redirect URI** and generate an OAuth client by clicking **Create Client**. [block:image] { "images": [ { "image": [ "https://files.readme.io/6f6570e-redirect_set_light_marked.png", "redirect_set_light marked.png", 2510, 1812, "#c7dbdc" ], "sizing": "smart" } ] } [/block] After creating the OAuth client, you will see a Client ID and Secret. [block:image] { "images": [ { "image": [ "https://files.readme.io/e6c488c-with_keys_light.png", "with_keys_light.png", 2510, 1812, "#c6dbdc" ], "sizing": "smart" } ] } [/block] To disable OAuth single sign-on, click the Revoke button. You will no longer be able to place orders on your customers' behalf using OAuth tokens and will not be able to authorize new tokens. [block:callout] { "type": "warning", "title": "Important!", "body": "If you disable OAuth, make sure you really mean it! If you re-enable it, you will get new Client ID and Secret values and will need to update your integration with the new values. Also, any customers that had previously authorized will need to re-authorize." } [/block] [block:api-header] { "title": "Authorization grant flow" } [/block] Now that you have the OAuth client set up, you can start the authorization grant flow for a customer. First, the customer must initiate a GET request to the authorization endpoint in Apruve. This is done by having them follow a link that you generate. The link will have the following format: `https://test.apruve.com/oauth2/authorize` in the test environment, and `https://app.apruve.com/oauth2/authorize` in production. The url must also have the following query parameters. [block:parameters] { "data": { "h-0": "Request query parameter", "h-1": "Description", "0-0": "client_id", "0-1": "The Client ID is provided when you generated the OAuth client in the first step.", "1-0": "redirect_uri", "1-1": "The Redirect URL you provided when generating the OAuth client in the first step. This is where the customer will be redirected to when the grant flow is complete.", "2-0": "response_type", "2-1": "The value for this is always `code`", "3-0": "state", "3-1": "An **optional** value that you can provide that we will include in the query parameters when redirecting the user to `redirect_uri` after the grant flow is complete." }, "cols": 2, "rows": 4 } [/block] Example Authorization URL `https://test.apruve.com/oauth2/authorize?client_id=5fd4dc5ce8c2d76f817c0b7b98d5fc0b3e06384b83fa7f2fdfe1f962bf92093a&redirect_uri=https%3A%2F%2Fspacelysprockets.com%2Foauth_callback&response_type=code&state=fa0424cef2f9350a6a53deb6baeed643c0a82365d1132113450e53e51f063103` For the following values: client_id: 5fd4dc5ce8c2d76f817c0b7b98d5fc0b3e06384b83fa7f2fdfe1f962bf92093a redirect_uri: https://spacelysprockets.com/oauth_callback state: fa0424cef2f9350a6a53deb6baeed643c0a82365d1132113450e53e51f063103 response_type: code This will prompt your customer to log into Apruve, after which we will show a page with options to **Authorize** or **Cancel** the request. [block:image] { "images": [ { "image": [ "https://files.readme.io/f7673da-authorize_light.png", "authorize_light.png", 2510, 1812, "#f8f9f9" ] } ] } [/block] [block:api-header] { "title": "Redirect back to your site" } [/block] The customer can select to **Cancel** or **Authorize** your request to operate on their behalf. In either case, we will send the client back to the `Redirect URI` the you initially provided and have used as a query parameter in the last step. We will use the following query parameters in this step. #### Redirect From Apruve [block:parameters] { "data": { "0-0": "code", "1-0": "state", "0-1": "A randomly generated code used for the next step. This will not be provided if the customer declined authorization.", "2-0": "error", "3-0": "error_description", "3-1": "Description of error, only provided if there was an error.", "1-1": "The optional state that you provided in the previous step. Use this to prevent cross-site request forgery attacks.", "2-1": "An error code that is only provided if there was an error or the customer declined authorization", "h-1": "Description", "h-0": "Request query parameter" }, "cols": 2, "rows": 4 } [/block] Example (success): `https://spacelysprockets.com/oauth_callback/?code=5559c688c82f17c0966afebaf07eb6889e758810793b8c9fa5b7e7b1372f2ae6&state=fa0424cef2f9350a6a53deb6baeed643c0a82365d1132113450e53e51f063103` Example (error): `https://spacelysprockets.com/oauth_callback/?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&state=fa0424cef2f9350a6a53deb6baeed643c0a82365d1132113450e53e51f063103` [block:api-header] { "title": "Request the token" } [/block] The final step is to send a request for the access token. In this step you will POST to the following url: `https://test.apruve.com/oauth2/token` for the test environment and `https://app.apruve.com/oauth2/token` for production. The request must have the following parameters: [block:parameters] { "data": { "2-0": "code", "2-1": "The code we provide to you as a query parameter in the redirect.", "3-0": "grant_type", "3-1": "This will always be `authorization_code`.", "4-0": "redirect_uri", "4-1": "The redirect uri that you provided when generating the client and that has been used in each of the previous steps.", "h-0": "Parameter", "h-1": "Description", "5-0": "state", "5-1": "The optional state that you provided in the previous step. Use this to prevent cross-site request forgery attacks.", "0-0": "client_id", "0-1": "The client ID we provided when you generated the OAuth client in the first step.", "1-0": "client_secret", "1-1": "The secret we provided when you generated the OAuth client in the first step." }, "cols": 2, "rows": 6 } [/block] If everything is successful, our response payload will contain the following data, which should be stored with the associated user in your system as they will be required to make requests on their behalf. #### Response From Apruve [block:parameters] { "data": { "0-0": "token", "0-1": "Access token used to authorize requests on behalf of your customer. This lasts for 120 min, before you need to use the refresh token to obtain a new one", "1-0": "refresh_token", "1-1": "Token used to obtain a new access token when it expires", "3-0": "corporate_account_id", "3-1": "The ID of your customer's corporate account in Apruve. This refers to the company that the user belongs to as opposed to the user itself.", "h-0": "Response Parameter", "h-1": "Description", "2-1": "The amount of time in seconds that the new access token will be valid before expiring.", "2-0": "expires_in" }, "cols": 2, "rows": 4 } [/block] [block:api-header] { "title": "Refreshing the token" } [/block] When the access token expires after 120 minutes, you need to obtain a new one using the refresh token. To do so, make a post to the same endpoint used to get the token originally, this time using the following parameters: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "client_id", "0-1": "The client ID we provided when you generated the OAuth client in the first step.", "1-1": "The secret we provided when you generated the OAuth client in the first step.", "1-0": "client_secret", "2-0": "refresh_token", "3-1": "This will always be `refresh_token`.", "3-0": "grant_type", "2-1": "The last `refresh_token` that you've received for this user." }, "cols": 2, "rows": 4 } [/block] If everything is successful, our response payload will contain the following data. The new `refresh_token` and `access_token` should be stored with the associated user in your system. #### Refresh Token Response From Apruve [block:parameters] { "data": { "h-0": "Response Parameter", "h-1": "Description", "0-0": "access_token", "0-1": "A new access token for this user", "1-0": "expires_in", "1-1": "The amount of time in seconds that the new access token will be valid before expiring.", "2-0": "refresh_token", "2-1": "A new refresh token for this user", "3-1": "The ID of your customer's corporate account in Apruve. This refers to the company that the user belongs to as opposed to the user itself.", "3-0": "corporate_account_id" }, "cols": 2, "rows": 4 } [/block] [block:api-header] { "title": "Using the access token in requests" } [/block] With the user's access token you can create orders on their behalf and get data about their account such as credit limit. In order to use the access token, you must put it in an Authorization header when making requests. For example: `Authorization: Bearer d068492b812fb8d94b0d824627cf27f4ae5e3a45fd7302537fe5fa060c44a550` If you get a 401 response code with the following error payload, it is time to request another access token, follow the previous step. You can also keep track of the expiration times on your end. [block:code] { "codes": [ { "code": "[\n {\n \"message\": \"Invalid authentication token.\"\n }\n]", "language": "json" } ] } [/block]