Generate an OAuth Token

HTTP Request

POST /oauth/token

Summary

Each request to the Global Ecommerce APIs requires authentication via an OAuth token. This API call generates the OAuth token based on the Base64-encoded value of the API key and secret associated with your Pitney Bowes developer account. The token expires after 10 hours, after which you must create a new one.

Note: If you do not have your API key and secret, retrieve them from Developer Hub.

To use this API, you must first use a Base64 encoder, such as https://www.base64encode.org/, to encode your API key and secret in the following format. Be sure to include the colon between the key and secret:

<API_key>:<API_secret>

Once you encode your key and secret, pass the encoded value via this API call and retrieve an OAuth token, which will be good for 10 hours. Use the token in all calls made to the Ecommerce APIs.

TIP: If you want to test the token without having to create shipments or merchants, use the Validate an Address API call, which requires only the token and an address.

Considerations

  1. Each authorization token in valid for 10 hours.

  2. It is recommended that each valid token be reused until it expires.

  3. Multiple concurrent valid tokens are allowed.

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/oauth/token
Production: https://shipping-api.pitneybowes.com/oauth/token

Note: The Base URL for Token Authentication differs from the base URL used for the other Ecommerce API operations.

Request Headers

Name

Description

Authorization

Required. Use Basic authentication to pass the Base64-encoded value of your developer account’s API key and secret.

Encode the key and secret in the following format. Be sure to include the colon between the key and secret:

<API_key>:<API_secret>

Pass the encoded value using Basic authentication:

Basic <encoded-value>

See the Sample Request after these tables.

Content-Type

Required. Set this to:

application/x-www-form-urlencoded

Request Elements

Name

Data Type

Description

grant_type

String

Required. Set this to:

client_credentials

Response Elements

Name

Data Type

Description

access_token

String

The OAuth token.

expiresIn

String

The period of time, in seconds, that the token is valid. It is recommended you reuse the token during this period.

A value of 35999 means the token is valid for just one second short of 10 hours. (10 hours x 60 minutes x 60 seconds = 36000 seconds)

issuedAt

String

The time expressed in milliseconds since Epoch Time. Epoch Time is the time on midnight on January 1, 1970 UTC.

Sample Request

In the following sample request, <Base64(key:secret)> is the Base64-encoded value of the developer’s API key and secret.

curl -X POST ".../oauth/token" \
-H "Authorization: Basic <Base64(key:secret)>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"

Sample Response

{
    "access_token": "m22wyEgfHlA0LudkGG9gG2xB04Cv",
    "tokenType": "BearerToken",
    "issuedAt": "1456851460568",
    "expiresIn": "35999",
    "clientID": "3W8mOJ1Gh5lItmFCHzz82SZO9rc2EBwS",
    "org": "pitneybowes"
}

Error Codes

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.