Authorization Failure with USPS v3 API

[skillmatic-co]

I'm getting:

USPS::Error (Authorization failure. Perhaps username and/or password is incorrect.)

Is authorization literally just including your USPS.com username like USPS.config.username = 'YOUR USERNAME'? I'm doing that and I'm still getting the error above. My App is showing as Approved on USPS.com and showing Public Access I as Enabled.

Do you not need to include your USPS App's API Consumer Key and/or Consumer Secret anywhere?

[bensheldon]

This library hasn't been updated in a while. Just visiting the USPS site, I think this gem might be for using the "Legacy Web Tools API Library".

[skillmatic-co]

@bensheldon yeah, it seems that there's now a V3 of the USPS API, and this library isn't for that.

Any idea if there's a wrapper out there for the V3 API?

[bensheldon]

I don't know of a wrapper. Looks like we just passed the sunset date. I'd accept it if someone wanted to update this one ;-)

[bensheldon]

fyi, it's looking like i'll update this gem to v3, though it might be a fairly substantial rewrite and API change: #37

[jtalk22]

This is expected — USPS retired the Web Tools XML API (which used USERID auth) on January 25, 2026. The new v3 REST API uses OAuth 2.0 client_credentials flow.

The usps gem would need a significant rewrite to support v3. In the meantime, you can call the v3 API directly:

require 'net/http'
require 'json'
require 'uri'

# Step 1: Get OAuth token
token_uri = URI('https://apis.usps.com/oauth2/v3/token')
token_resp = Net::HTTP.post_form(token_uri, {
  'grant_type' => 'client_credentials',
  'client_id' => ENV['USPS_CLIENT_ID'],
  'client_secret' => ENV['USPS_CLIENT_SECRET'],
  'scope' => 'addresses'
})
access_token = JSON.parse(token_resp.body)['access_token']

# Step 2: Validate address
uri = URI('https://apis.usps.com/addresses/v3/address')
uri.query = URI.encode_www_form(
  streetAddress: '1600 Pennsylvania Ave',
  city: 'Washington',
  state: 'DC',
  ZIPCode: '20500'
)
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{access_token}"
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
result = JSON.parse(resp.body)
puts result.dig('address', 'DPVConfirmation') # "Y" = deliverable

Register for new API credentials at https://developer.usps.com (the old Web Tools registration no longer works).

Key gotcha: the token endpoint uses application/x-www-form-urlencoded, not JSON. The API endpoints return JSON.