Generate an OAuth Token

HTTP Request

POST /oauth/token

Summary

Each request to the PB Shipping 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 PB Shipping APIs 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>

After you pass the encoded value via the API and retrieve an OAuth token, use the token in all calls made to the PB Shipping APIs. 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.

Things to Consider

  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 URIs

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

Note: The Base URL for Token Authentication differs from the base URL used for the other PB Shipping APIs.

Request Headers

Name Data Type Description
Authorization String

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 String

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 Epoch Time. Epoch Time is the number of seconds since 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 PB Shipping APIs error codes, see Error Codes.