Getting Started
In order to authenticate to the Whiplash V2 APi, you will need the following:
- a client_id, provided to you from Whiplash.
- a client_secret, provided to you from whiplash.
- a user_scope, which will be user_read or user_manage. This will be provided to you from Whiplash.
- a redirect_uri, which you can provide to us during V2 signup, or we can assign a temporary one to you.
- a Whiplash web app login and password for the appropriate API environment (sandbox for testing, production for real data).
The Whiplash V2 API uses Oauth2 as our authentication scheme. This allows API requests to act on behalf of whoever authenticates with it. When you authenticate as a user of a company, it allows you access to all of that customer's resources such as orders and items.
Note: You will be required to manually create your initial Oauth token via Whiplash app authentication. Once the relationship has been established, you can skip the manual login flow and just request refresh tokens.
Note: You will be required to manually create your initial Oauth token via Whiplash app authentication. Once the relationship has been established, you can skip the manual login flow and just request refresh tokens.
Authenticating
Step 1
- In a browser, issue a GET request to /oauth/authorize
- make sure you send over the following parameters
- scope=YOUR USER SCOPE (usually user_read or user_manage)
- response_type=code
- redirect_uri=YOUR REDIRECT_URI FROM ABOVE
- client_id=YOUR CLIENT ID FROM ABOVE
an example request is:
- https://sandbox.getwhiplash.com/oauth/authorize?scope=user_manage&response_type=code&redirect_uri=https://hookbin.com/bin/vLNL1rj9&client_id=dbbd69223a50f6d347bb6c1110da12c69a34b1f0a3e69902c5db3e3a03bf58d5
You will be prompted to authenticate in the Whiplash web app, do so with your login credentials.
Once you login, you will be a redirect to your redirect_uri with the parameter code appended to it. For example:
- https://hookbin.com/bin/vLNL1rj9?code=d535aaf63fc8e56e55dffaaf3387d8a184d5a4d5ff2eb6a35344ae20fb6df212
(Note: we use hookbin.com just for an example, you could just as easily have this call an endpoint in your application.)
Retain this code value, it shall be refered to as RETURNED_CODE
Step 2
Make a POST to /oauth/token and include the following key/values in your post body:
- redirect_uri=YOUR REDIRECT_URI
- code=RETURNED_CODE
- client_id=YOUR CLIENT ID
- client_secret=YOUR CLIENT SECRET
- scope=YOUR USER SCOPE
- grant_type=authorization_code
This will respond with a JSON object like:
{
"access_token": "ddb8c266333a19...",
"token_type": "bearer",
"expires_in": 7200,
"scope": "user_manage",
"created_at": 1510698627
"refresh_token":"8c488ab5f75d61..."
}This token will remain active for 2 hours, after that you will need to get a refresh token. Hang onto the value of "refresh_token" so you will be able to get new tokens when this one expires.
Step 3
You can now make an API request to Whiplash on behalf of the user you authenticated as in Step 1.
Simply add the Header Authorization:"Bearer YOUR_ACCESS_TOKEN" (using the above example - Authorization: "Bearer ddb8c266333a19..." )
With that Header set, you can now call V2 API endpoints such as https://sandbox.getwhiplash.com/api/v2/items
Refresh Tokens
You can programatically get refresh tokens by sending a POST to /oauth/token with the following params:
- grant_type="refresh_token"
- refresh_token=YOUR REFRESH TOKEN
- client_id=YOUR CLIENT ID
- client_secret=YOUR CLIENT SECRET
This will return a new token response like:
{
"access_token": "ddb8c266333a19...",
"token_type": "bearer",
"expires_in": 7200,
"scope": "user_manage",
"created_at": 1510698627
"refresh_token":"8c488ab5f75d61..."
}You can now use the newly returned access_token as the value for your Authorization Header and retain the new refresh_token for future refresh calls.