Authentication

Sendbox API authentication for integrating with your application.

Steps on how to get your access token

Kindly note that you are to use staging url for all your test request. Be sure to change them to live when you are done with development.

  • Visit Sendbox for developers and sign up then navigate go to your dashboard and create a new app.

  • When creating this app, some fields are required.

Name: Your App Name 
Description : A breif description about your app
Redirect URI : A url that sendbox will post your app code to so you 
can make a request to oauth endpoint.

You can create more than one Redirect URI.

You can store your keys somewhere and then proceed to how you can get your refreash token in this part of the docs.

What is next ?

Let's assume you are building a multi-vendor site this means you have different sellers on your store so shipment will come from differnet accounts. follow the steps below on the complete Oauth flow.

  • Once this is done, you will be given your app id and a secret.

  • Create your redirect url. This is the url you are supposed to redirect your users to after they have given you access to their account.

  • Build a senbox url with the app Id ,redirect url, and the client secret. Also add the scopes (I.e permissions you need access to like profile, shipping, payment etc)

  • Then make a get request to access token endpoint with all these parameters as path parameters then your access token is returned in the response.

All these steps are explained in details below. Including steps required of your users.

Login

When someone is logged into your app, and you want to access their Sendbox data, you can use the login dialog to prompt them to do both. If they aren't logged into Sendbox, they will be prompted to login and then redirected back to your app. This is automatically detected, so you don't need to do anything extra to enable this behavior.

Your app must initiate a redirect to an endpoint which will display the login dialog:

Staging URL: 
https://live.sendbox.co/oauth/access?app_id={app-id}&redirect_url={redirect-url}&state={state-param}

Live URL: 
https://live.sendbox.co/oauth/access?app_id={app-id}&redirect_url={redirect-url}&state={state-param}

This endpoint has the following required parameters:

For example, if your login request looks like:

Staging URL:
https://sandbox.staging.sendbox.co/oauth/access?app_id=12345678&redirect_url=https://www.testing.com/login&state=234567890


Live URL:
https://live.sendbox.co/oauth/access?app_id=12345678&redirect_url=https://www.testing.com/login&state=234567890

Then your redirect URL would be called with this:

https://www.testing.com/login?state=234567890

Login Response

At this point in the login flow, the person will see the Login dialog and will have a choice of whether to cancel or to let the app access their data.

If the person using the app chooses OK on the Login dialog, they grant access to their public profile, friend list and any additional Permissions your app requested.

Confirm Identity

Because this redirect flow involves browsers being redirected to URLs in your app from the Login dialog, traffic could directly access this URL with made-up fragments or parameters. If your app assumed these were valid parameters, the made-up data would be used by your app for potentially malicious purposes. As a result, your app should confirm that the person using the app is the same person that you have response data for before generating an access token for them. Confirming identity is accomplished in different ways depending on the response_type received above:

When code is received, it has to be exchanged for an access token using an endpoint. The call will need to be server-to-server, since it involves your app secret. (Your app secret should never end up in client code.)

As this API call requires using an app access token, never make this call from a client. Instead make this call from a server where you can securely store your app secret.

Access Token

To get an access token, make an HTTP GET request to the following OAuth endpoint:

Get Access Token

GET https://live.sendbox.co/oauth/access/access_token?app_id={app-id}&redirect_url={redirect-url}&client_secret={client-secret}&code={code-parameter}

Path Parameters

{
 "access_token": {access-token}, 
 "Refresh_token":{refresh-token}

"expires_in": {seconds-til-expiration}

}








Staging URL: 
https://sandbox.staging.sendbox.co/oauth/access/access_token?app_id={app-id}&redirect_url={redirect-url}&client_secret={client-secret}&code={code-parameter}

Refresh Token

Refresh token comes back in the response for access token. You are advised to save this refresh token somewhere. It will be used to get a new access token when your access token expires. To do this, you pass refresh token in header and do a get request to oauth end point again this will return a new access token.

Refresh token is only used when the access token expires.

when you call the refresh endpoint you get a new access_token and a new refresh_token you're expected to save both as the initial refresh token you use when making the request expires after use.

Get New Access Token

GET https://live.sendbox.co/oauth/access/{app_id}/refresh?app_id={app_id}&client_secret={client_secret}

This helps you get a new access token after the previous one expires by calling refresh token endpoint. This returns a new access token and refresh token

Headers

{
 "access_token": {access-token}, 
 "Refresh_token":{refresh-token}
 }
Staging URL:
https://sandbox.staging.sendbox.co/oauth/access/{app_id}/refresh?app_id={app_id}&client_secret={client_secret}

This app secret should never be included in client-side code or in binaries that could be decompiled. It is extremely important that it remains completely secret as it is the core of the security of your app and all the people using it. code. The parameter received from the Login Dialog redirect above.

Last updated