Generate an OAuth Token

HTTP Request

POST /oauth/token

Summary

Each request to the Pitney Bowes 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 Pitney Bowes developer account. The validity period of the token is provided in the expiresIn field of the response. Once the token expires, a new token must be created.

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 few hours. Use the token in all calls made to the PB Shipping 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 is valid for the period specified in the expiresIn response field.

  2. It is recommended to reuse each valid token until it expires.

  3. Multiple concurrent valid tokens are allowed but are not advised.

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 PB Shipping 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 28800 means the token is valid for just one second short of 8 hours. (8 hours x 60 minutes x 60 seconds = 28800 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": "eyJraWQiOiJ6eFRYUFY4emF4dXRMSGR5RVZVUXgwaEJ2QmJlVm42STN0QldUdEtoNWZ3IiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULmdsVmw2eWZ2ajNXX2tEbmNlTXdLRTBYV2laVkZZS08xcUw5c3M4VmZXcGMiLCJpc3MiOiJodHRwczovL3BpdG5leWJvd2VzLXN0YWJsZS5va3RhcHJldmlldy5jb20vb2F1dGgyL2F1czI4ZW55M20zNXNkbk0xMGg4IiwiYXVkIjoiaHR0cHM6Ly9hcGlzLXN0YWdpbmcucGl0bmV5Ym93ZXMuY29tIiwic3ViIjoibjVLcU5IeU1wZ1c1YXVRME5zUXVSU2JianFuOW0xOTUiLCJpYXQiOjE3MzU4MDI4ODMsImV4cCI6MTczNTgzMTY4MywiY2lkIjoibjVLcU5IeU1wZ1c1YXVRME5zUXVSU2JianFuOW0xOTUiLCJzY3AiOlsiYXBpbS5leHRlcm5hbCJdLCJ3ZWJob29rUHJvY2Vzc2VkIjoiU3VjY2VzcyIsImFwaW1FbnRJRCI6Ijk1MTU4MzA0IiwiYXBpbVN1YlVJRCI6IlNFWW9GWnJrYTdOSUNnNisxTXBXLzRMVmlmZzhBb3dPZ05seWc5Z1FjR3MvSFBOcm1POGlrVzVBQnRJTk5kWTAifQ.ro3tfYLZuoC7cU0naOyaVgRm3udP1UIP5q8ogRDFvqH9YNvvrQEt_49HzEy9LAHhJeHF2xXZoK32OvSqVnS_KLWrdzbGHaORXw-VfeQtwNVTCiEpK8XLcVT0fmEnqVVUzu1EQY25rzUnqfKm2WtylzlyZDQ_9FULWZL92edUTUbIO9aUdXgF7AeQnQUvnfS13STEox4DkW_6ODy1yYiT0FiL8HCH_Ro6u3oBImR-QqkPCgybtMlHYNqz7FgLg3FZ5PoUeibGnnSFckdGjoWHMiSofb3c8x_Rnfpo2XWCL521u3mD33HCzvFXk7IQgEmau5YlmkO1Gb-0WamjVutD-w",
 "tokenType": "BearerToken",
 "issuedAt": "1735802883000",
 "expiresIn": "28800",
 "clientID": "n5KqNHyMpgW5auQ0NsQuRSbbjqn9m195",
 "org": "pitneybowes-qa"

}

Error Codes

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