Migrating on-prem to cloud using /oauth2/v3/authorize

[SteveChristyMidway]

Describe the bug
I received instructions on upgrading from the on-prem to new cloud based APIs. Option 2 seems preferrable to me, which was:

Steps Required: 

Platform uses GET Authorize API to generate Cloud-compatible authorization codes
See below for API instructions
Platforms exchange authorization codes for access and refresh tokens in the Cloud 
Platforms call new Cloud API base URL (apis.usps.com) with Cloud-compatible tokens 
Redirect from api.usps.com to apis.usps.com implemented
Redirect all new onboards to new COP Cloud URL
Base URL: https://cop.usps.com/cop-navigator?wf=apis_merchant_user 
Sample URL (change highlighted fields tailored to your platform): https://cop.usps.com/cop-navigator?wf=apis_merchant_user&client_id=SAuNbiGoAqO0oeG58IRQGp&state=7512&redirect_uri=https://mycompany.com&platform=PlatformName&reauth=true
 

GET Authorize API Instructions 

1.  Generate an OAuth access token using the Platform client credentials 

2.  Execute a GET OAuth Authorize request to retrieve the desired Merchant Authorization Code 
§    Path: /oauth2/v3/authorize 
§    Parameters: 
·               response_code 
o      The type of response being requested, 'code' in this case. 
·               redirect_uri 
o      The redirection url that the client application has been previously registered with. This input must be an exact match with the one(s) previously registered. 
·               client_id 
o      The unique identifier of the client application making the request. 
·               user_id 
o      The unique subject identifier of the merchant's account. 
o      This can be obtained from the decoded merchant access token JWT or retrieved by entering the merchant access token in the User Info API (same as “sub_id”).
·               state (optional) 
o      A state parameter used by the client application to mitigate man-in-the-middle interception. 

§    Sample cURL: 
·               curl --location ‘https://apis.usps.com/oauth2/v3/authorize?response_type=code&redirect_uri=https%3A%2F%2Fdevelopers.usps.com&state=nonce%3DKT&client_id=23jlipoqw2094ucbtmOu1ikvDuLtLljsVbIS0238mlZeg&user_id=31752098' \ 
--header 'User-Agent: APITester' \ 
--header 'Accept: application/json' \ 
--header 'Authorization: Bearer null' 

§    Sample Response (HTTP Redirect; appears in the Location header of the response): 
·               https://developers.usps.com/?code=gXBTHR85&state=nonce=KT 

3.  Exchange the authorization code for new refresh/access tokens 
§    Path: /oauth2/v3/token 
§    No change to the standard process currently being used post-merchant authorization 
§    The authorization code must be exchanged within 5 minutes of generation 

However, when I try step 2, my redirect URL looks like https://mywebsite.com/USPS/Callback?error=unauthorized_client&error_description=The client is not authorized to request an authorization code using this method.&error_uri=https%3A%2F%2Fdatatracker.ietf.org%2Fdoc%2Fhtml%2Frfc6749%23section-4.1.2.1&state=nonce

Is it possible this is the result of some configuration on my platform account? Or perhaps just not using the API correctly?

To Reproduce
Steps to reproduce the behavior:
I get a platform bearer token (grant_type = client_credentials, using my client id and secret) and my API request for step 2 looks like

curl -v 'https://apis.usps.com/oauth2/v3/authorize?response_type=code&redirect_uri=https%3A%2F%2Fmywebsite.com%2FUSPS%2FCallback&state=nonce&client_id=REDACTED&user_id=REDACTED' --header 'Authorization: Bearer REDACTED'

Expected behavior
A redirect URL indicating success with an authorization code that I can use to get new cloud API compatible access tokens/refresh tokens.

Additional context
These steps were supposed to have been completed by January 26th, but I was told I received a short extension to make the necessary changes and migrate.
My client ID is qgOiSDatb9I4TY7xAHnVuoqxZ4V7eQmf

[jtalk22]

The unauthorized_client error means your application isn't registered for the authorization_code grant type on the USPS platform. By default, applications are configured for client_credentials only.

Two things to check:

1. Your app needs the authorization code grant enabled.

Contact USPS API support (https://emailus.usps.com/s/web-tools-inquiry) and request that the authorization_code grant type be enabled on your application. Include your client ID and explain you're a platform doing multi-merchant OAuth (the /oauth2/v3/authorize flow).

This is separate from the client_credentials flow — the USPS Developer Portal doesn't expose this configuration, so it requires a support request.

2. Verify your redirect URI is registered exactly.

The redirect_uri parameter must match exactly what's registered with your application — including trailing slashes, scheme (https), and path. If you registered https://mywebsite.com/USPS/Callback but send https://mywebsite.com/usps/callback, it will fail.

Alternative approach (if you control the merchant credentials):

If your merchants have their own USPS client IDs/secrets (BYOK model), you can skip the authorization code flow entirely and use client_credentials with each merchant's credentials:

POST https://apis.usps.com/oauth2/v3/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=MERCHANT_CLIENT_ID
&client_secret=MERCHANT_CLIENT_SECRET
&scope=addresses tracking prices

This is what "BYOK" (Bring Your Own Keys) platforms do — each merchant registers at developer.usps.com and provides their credentials to your platform. No authorization code exchange needed.

More on the v3 OAuth flows and enrollment: https://revaddress.com/blog/usps-crid-mid-enrollment