1. Help Center
  2. RyderShip Application Developers
  3. RyderShip API
  4. Rydership API

Authentication for the V2 API

Jodi Croft
Jodi Croft
  • Updated

In this article:

Getting started

In order to authenticate to the RyderShip V2 API, you will need the following:
  • application_id, provided to you from RyderShip.
  • client_secret, provided to you from RyderShip.
  • user_scope, which will be user_read or user_manage. This will be provided to you from RyderShip.
  • callback_url, which you can provide to us during V2 signup, or we can assign a temporary one to you.
  • A RyderShip web app login and password for the appropriate API environment (Sandbox for testing, production for real data).
The RyderShip 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 RyderShip App authentication. Once the relationship has been established, you can skip the manual login flow and just request refresh tokens.

Back to top

Authenticating

Sandbox URL: https://sandbox.whiplash.app

Production URL: https://www.getwhiplash.com/

Number1.png  GET request to authorize

  •  In a browser, issue a GET request to /oauth/authorize
  •  Include the following parameters:
    •    scope=YOUR USER SCOPE (usually user_read and/or user_manage) 
    •    response_type=code
    •    redirect_uri=YOUR CALLBACK_URL FROM ABOVE
    •    client_id=YOUR APPLICATION ID FROM ABOVE
   An example request would be: 
  • https://sandbox.whiplash.app/oauth/authorize?scope=user_manage&response_type=code&redirect_uri=https://hookbin.com/bin/vLNL1rj9&client_id=dbbd69223a50f6d347bb6c1110da12c69a34b1f0a3e69902c5db3e3a03bf58d5
If not already logged in, you will be prompted to authenticate in the RyderShip web app. Do so with your login credentials.

Once you log in, you will be redirected to your redirect_uri with the parameter code appended to it. 

For example:

Screen_Shot_2022-02-10_at_9.05.55_AM.jpg

 

Note: We use hookbin.com simply as an example. You can just as easily have this call an endpoint in your application

Retain this code value, referred to as RETURNED_CODE.

Number2.png  Make a POST

Make a POST to /oauth/token and include the following key/values in your post body:

  •    redirect_uri=YOUR CALLBACK_URL
  •    code=RETURNED_CODE
  •    client_id=YOUR APPLICATION ID 
  •    client_secret=YOUR CLIENT SECRET
  •    scope=YOUR USER SCOPE
  •    grant_type=authorization_code

  
Auth request.png

 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, you will need to get a refresh token.  Hang on to the value of "refresh_token" so you will be able to get new tokens when this one expires.

TIP: If you get an "Invalid_grant" error, please reach out to the Tech Support Team. This is likely due to an expired or invalid callback URL.

Number3.png  Make an API request to RyderShip

You can now make an API request to RyderShip on behalf of the user you authenticated as in Step 1 - GET request to authorize. 

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.whiplash.app/api/v2/items

Expiration & Refresh tokens

The access token has a “time-to-live” (ttl), which is the maximum time that the access token will be valid for use within the application. By default, all tokens have a system-defined ttl of 2 hours (7200 seconds). When a token is created, the API response will return the ttl in seconds.

You will use your refresh token that gets regenerated every time you use the previous token to re-authenticate periodically every 2 hours. We recommend storing refresh tokens in a secure location, such as a password-protected file system or an encrypted database to share amongst your team members who require them to make API calls.

You can programmatically get refresh tokens by sending a POST Request to /oauth/token with the following params:

  • grant_type="refresh_token"
  • refresh_token=YOUR REFRESH TOKEN
  • client_id=YOUR APPLICATION 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.

V2 Rate Limiting

Our platform has a rate limit of 10 requests per second to ensure smooth performance and prevent overload. 

You can find the rate limit and how many attempts you have left in the response header.

The fields relevant to this are:

  • X-Ratelimit-Limit - Your rate limit caps out at this value
  • X-Ratelimit-Remaining - How many attempts you have left

Example in Postman/Post Request:

Postman.jpg

Troubleshooting API issues

When you are having issues with the API (for example, if your access token is revoked) refresh the token by following the directions above, under "Expiration and Refresh Tokens". 

If refreshing the token does not work, try obtaining a new token from scratch by following the directions in this article under "Authenticating".

If the issues persist, please contact support at support@whiplash.com for further assistance. 

Back to top

 

Related questions:

How do I authenticate to the Whiplash V2 API?

How do I obtain a refresh token?

How do I troubleshoot an issue with the API? 

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request