Authorization
Authorization
Taptouch API support OAuth 2.0 to allow developers to get a user access token to access their data. OAuth 2.0 is a specification outlined in RFC 6749 that allows third-party services to make requests on behalf of a user without accessing passwords and other sensitive information.
Recommends
We strongly recommend that you use a OAuth Library to perform the authorization grant and token exchanges for OAuth 2.0.
Endpoints
Authorization Endpoint
GET https://api.taptouch.net/auth/v2/authorize
The Authorize endpoint allows you to redirect a user to the authorization URL for your developer account.
Authorization:
None
Query Parameters:
| Parameter | Description |
|---|---|
| response_type | OAuth 2.0 response type. code is the only acceptable input at this time. |
| client_id | The client ID of your developer account. |
| scope | Space delimited list of grant Scopes you would like to have permission to access on behalf of the user. |
| state(optional) | An opaque value that is used to preventing cross-site access forgery. |
| redirect_uri | The URI we will redirect back to after an authorization by the resource owner. The base of the URI must match the redirect_uri used during the registration of your developer account. |
Token Exchange Endpoint
POST https://api.taptouch.net/auth/v2/token
The token exchange endpoint allows you to authorize your developer account and get an access_token using the authorization_code grant. You can also refresh the access_token using the refresh_token grant.
Authorization:
None
POST Parameters:
| Parameter | Description |
|---|---|
| client_id | The client ID of your developer account. |
| client_secret | The Client Secret of your developer account. |
| grant_type | Grant Type |
| redirect_uri | The URI we will redirect back to after an authorization by the resource owner. The base of the URI must match the redirect_uri used during the registration of your developer account. |
| code | The authorization code returned by Taptouch server |
| scope | Space delimited list of grant Scopes you would like to have permission to access on behalf of the user. |
Grant Type
OAuth 2.0 specifies how a client application obtains an access token.
Grant Type (grant_type) | Description |
|---|---|
authorization_code | Used by web and mobile apps with a backend. After user authorization, the client receives a short-lived authorization code, which is exchanged for an access token (and optionally a refresh token) via a secure backchannel. Supports PKCE for public clients. |
client_credentials | Used for machine-to-machine (M2M) authentication. The client acts on its own behalf (not on behalf of a user). Authenticates with its client_id and client_secret to obtain an access token. |
refresh_token | Used to obtain a new access token (and optionally a new refresh token) after the original access token has expired. Requires a valid refresh_token issued during a previous authorization. |
Scopes
The following scopes are available for use with the Taptouch APIs.
| Scope | Grand Type | Description |
|---|---|---|
| integration.store | authorization_code or client_credentials | Permission to Store API |
| integration.order | client_credentials | Permission to Order API |
| integration.inventory | client_credentials | Permission to Inventory API |
Each endpoint requires one of the scopes listed above.
Multiple Scopes
Multiple scopes can be authorized using the same access token
Quickstart
1. Redirect the user to the authorize endpoint
Allow users on your website to authenticate themselves with Taptouch by redirecting them to the following URL. Where APPLICATION_ID and REDIRECT_URI are the values specific to your app, and the scope parameter is the relevant Taptouch OAuth2 scopes your want access to (more information: Scopes).
https://api.taptouch.net/auth/v2/authorize?scope=SCOPE1+SCOPE2&client_id=YOUR_APPLICATION_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code
2. Catch the request to your redirect URI
The Taptouch server will then redirect the request back to your redirect URI, with a request code in the URL parameters. So if your redirect URI is https://mysite.com/callback then the request will be made to https://mysite.com/callback?code=AUTHORIZATION_CODE.
3. Make a POST request to the token endpoint
Now that you’ve got your authorization code, you can finally make the POST request to get your access token.
From your server/application make a POST request to https://api.taptouch.net/auth/v2/token.
curl https://api.taptouch.net/auth/v2/token -X POST -H "Cache-Control: no-cache" \
-F "client_id=YOUR_APPLICATION_ID" \
-F "client_secret=YOUR_SECRET" \
-F "code=AUTHORIZATION_CODE" \
-F "redirect_uri=YOUR_REDIRECT_URI" \
-F "grant_type=authorization_code"
The response should look something like this:
{
"access_token": "eyJraWQiOiIyNjR3456lYS1hYWExLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJqdEBpdmlkYS5jb20uYXUiLCJhdWQiOiJNQ1NzM2tXeWhLMFhFREZNT1ZMS0MzMG5jd0l4NFRmZSIsIm5iZiI6MTY3NjY5MzcyOCwic2NvcGUiOlsiaW50ZWdyYXRpb24uc3RvcmUiLCJpbnRlZ3JhdGlvbi5pbnZlbnRvcnkiXSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDg1IiwiZXhwIjoxNjc5Mjg1NzI4LCJpYXQiOjE2NzY2OTM3Mjh9.jiMmqJjzlZJd0GMT5ebeesu90_pDOIp9dAop9AH01Hs7GUk9NS3xLGONLU7-b8f7Mm92XIW7XzF8sDGDyUZFKXXz90qZcomCC4yZLhPxDUbyvERrEs3ohCA2sE_fwGwUe4GdVDp6EHw3pAgS4ZZXGiwJK2S6E96Ygbu3zmOB6UEMasjJrhkzss84R7nwZtajqbwkiJ2XoMqMZ6ZknrcjhFYaaL-cIf3LkkSLEtqA4uKnT2eZIY22xrWICD3Y2aCuAsXEsZRR3yKpylgIPT3KN8AphqwnznooI1V8hLckD9T38LPv4EsNGrUQNQ4Dzuq-u8JE8HnFjzXhl2fliMbfSQ",
"refresh_token": "mNl4ertT1ZVluEL31HivSf3NCw0Auy_fcgHCXA2XD8D20uS3jJgl-S1o0MHSE_NjW-cHdQhTK02pFqfJY2f_FxAA6Q37fc0q5N8Gttp-VQ3709pmqiiqnh9RHMJgsijl",
"scope": "integration.store integration.inventory",
"token_type": "Bearer",
"expires_in": 172800
}
Tips
expires_in is in seconds, so your token will last 2 days. To learn how to refresh your token, see Refreshing your Token
4. Making Requests
Once either of the above authentication methods have been completed, you’ll have an access token.
Your access token will look something like this:
eyJraWQiOiIyNjR3456lYS1hYWExLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJqdEBpdmlkYS5jb20uYXUiLCJhdWQiOiJNQ1NzM2tXeWhLMFhFREZNT1ZMS0MzMG5jd0l4NFRmZSIsIm5iZiI6MTY3NjY5MzcyOCwic2NvcGUiOlsiaW50ZWdyYXRpb24uc3RvcmUiLCJpbnRlZ3JhdGlvbi5pbnZlbnRvcnkiXSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDg1IiwiZXhwIjoxNjc5Mjg1NzI4LCJpYXQiOjE2NzY2OTM3Mjh9.jiMmqJjzlZJd0GMT5ebeesu90_pDOIp9dAop9AH01Hs7GUk9NS3xLGONLU7-b8f7Mm92XIW7XzF8sDGDyUZFKXXz90qZcomCC4yZLhPxDUbyvERrEs3ohCA2sE_fwGwUe4GdVDp6EHw3pAgS4ZZXGiwJK2S6E96Ygbu3zmOB6UEMasjJrhkzss84R7nwZtajqbwkiJ2XoMqMZ6ZknrcjhFYaaL-cIf3LkkSLEtqA4uKnT2eZIY22xrWICD3Y2aCuAsXEsZRR3yKpylgIPT3KN8AphqwnznooI1V8hLckD9T38LPv4EsNGrUQNQ4Dzuq-u8JE8HnFjzXhl2fliMbfSQ
From here on out all requests you make to the Taptouch API must include the token in the header.
Authorization: bearer eyJraWQiOiIyNjR3456lYS1hYWExLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJqdEBpdmlkYS5jb20uYXUiLCJhdWQiOiJNQ1NzM2tXeWhLMFhFREZNT1ZMS0MzMG5jd0l4NFRmZSIsIm5iZiI6MTY3NjY5MzcyOCwic2NvcGUiOlsiaW50ZWdyYXRpb24uc3RvcmUiLCJpbnRlZ3JhdGlvbi5pbnZlbnRvcnkiXSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDg1IiwiZXhwIjoxNjc5Mjg1NzI4LCJpYXQiOjE2NzY2OTM3Mjh9.jiMmqJjzlZJd0GMT5ebeesu90_pDOIp9dAop9AH01Hs7GUk9NS3xLGONLU7-b8f7Mm92XIW7XzF8sDGDyUZFKXXz90qZcomCC4yZLhPxDUbyvERrEs3ohCA2sE_fwGwUe4GdVDp6EHw3pAgS4ZZXGiwJK2S6E96Ygbu3zmOB6UEMasjJrhkzss84R7nwZtajqbwkiJ2XoMqMZ6ZknrcjhFYaaL-cIf3LkkSLEtqA4uKnT2eZIY22xrWICD3Y2aCuAsXEsZRR3yKpylgIPT3KN8AphqwnznooI1V8hLckD9T38LPv4EsNGrUQNQ4Dzuq-u8JE8HnFjzXhl2fliMbfSQ
For example of a request store items of merchant that just authenticated. like so:
curl --header "Authorization: bearer eyJraWQiOiIyNjR3456lYS1hYWExLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJqdEBpdmlkYS5jb20uYXUiLCJhdWQiOiJNQ1NzM2tXeWhLMFhFREZNT1ZMS0MzMG5jd0l4NFRmZSIsIm5iZiI6MTY3NjY5MzcyOCwic2NvcGUiOlsiaW50ZWdyYXRpb24uc3RvcmUiLCJpbnRlZ3JhdGlvbi5pbnZlbnRvcnkiXSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDg1IiwiZXhwIjoxNjc5Mjg1NzI4LCJpYXQiOjE2NzY2OTM3Mjh9.jiMmqJjzlZJd0GMT5ebeesu90_pDOIp9dAop9AH01Hs7GUk9NS3xLGONLU7-b8f7Mm92XIW7XzF8sDGDyUZFKXXz90qZcomCC4yZLhPxDUbyvERrEs3ohCA2sE_fwGwUe4GdVDp6EHw3pAgS4ZZXGiwJK2S6E96Ygbu3zmOB6UEMasjJrhkzss84R7nwZtajqbwkiJ2XoMqMZ6ZknrcjhFYaaL-cIf3LkkSLEtqA4uKnT2eZIY22xrWICD3Y2aCuAsXEsZRR3yKpylgIPT3KN8AphqwnznooI1V8hLckD9T38LPv4EsNGrUQNQ4Dzuq-u8JE8HnFjzXhl2fliMbfSQ" \
https://api.taptouch.net/integration/v1/stores
5. Refreshing your Token.
If your token expires, you can using the the refresh_token got above to refresh it by making a POST request to https://api.taptouch.net/auth/v2/token.
curl https://api.taptouch.net/auth/v2/token -X POST -H "Cache-Control: no-cache" \
-F "client_id=YOUR_APPLICATION_ID" \
-F "client_secret=YOUR_SECRET" \
-F "refresh_token=REFRESH_TOKEN" \
-F "grant_type=refresh_token"
The response should look something like this:
{
"access_token": "eyJraWQiOiIyNjRhZWJlwrthYWExLTExZWQtYWZhMS0wMjQyYWMxMjAwMDIiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJqdEBpdmlkYS5jb20uYXUiLCJhdWQiOiJNQ1NzM2tXeWhLMFhFREZNT1ZMS0MzMG5jd0l4NFRmZSIsIm5iZiI6MTY3NjcwMTc4Mywic2NvcGUiOlsiaW50ZWdyYXRpb24uc3RvcmUiLCJpbnRlZ3JhdGlvbi5pbnZlbnRvcnkiXSwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDg1IiwiZXhwIjoxNjc5MjkzNzgzLCJpYXQiOjE2NzY3MDE3ODN9.X6l6PWk50fVbx_jxcpKtf9JGiydzix4KQ6UAP8r7pNa0OivFEaOfXprouMzuN1AwWT7ChubB1Ud5jKIW40g3BLp43nik3KB5eDz85KVSBhlqVLMVg-SYqjYSd9uxl9kZhC6dWsPV6uTkdfJWBXuMHr7Q03E-xC8pxM4EgNK5YLqfgdVGLnJdr3N8goeIwqTq95GDxzhJEaPqAneWVZOCXpVzywlUx6ELF5g3x3xI1sMykl_zZ3zI-BA6rtC0to4K8KDrIPZARmtBhSp216kmP_eFZOA4-fzYtdMQRqqEqN9xCVvz4c39EZfj66zQ599QNdTtGfh1HwnGj7PMcbaQYA",
"refresh_token": "mNl4cbzT1ZVluE3feHivSf3NCw0Auy_fcgHCXA2XD8D20uS3jJgl-S1o0MHSE_NjW-cHdQhTK02pFqfJY2f_FxAA6Q37fc0q5N8Gttp-VQ3709pmqiiqnh9RHMJgsijl",
"scope": "integration.store integration.inventory",
"token_type": "Bearer",
"expires_in": 172800
}
You can now go on using this new access token for another 2 days.
Notices
If your developer account’s access is revoked by the user, then you will need to run through the authentication process again to obtain a new access token.
Tips
Although the tokens only last for 2 days, you can refresh your token within 4 days. The refresh token can only be used once.