Developer Guide
Use the Developer Guide to find the onboarding process steps, information about authentication methods, and a comprehensive list of the available ABC API endpoints.
Developer GUide
Authorization Methods
Sandbox
Production
Grant Type Decision Guide
Depending on the requirements of your application, you will want to utilize different OAuth 2.0 grants to authorize access to the connect partner endpoints. Below is a decision guide:
Note: Different scopes are valid for Authorization Code vs Client Credentials grant types. Use the chart above in conjunction with the desired scopes to determine what grants should be used for your purposes.
Authorization Code
The authorization code flow is required when your application is taking actions on behalf of an ABC Supply customer.
This flow has the following steps:
- Your application requests an authorization code from the authorization server.
- The auth server presents an authentication prompt to the user’s browser.
- The user signs in with their ABC Supply credentials and and provides consent.
- The browser receives an authorization code from the authorization server (Okta) after the user is authenticated. The authorization code is passed to your app.
- Your app sends this code and the client secret to the authorization server.
- The authorization server returns an access token, and optionally a refresh token.
- Your app can now use these tokens to call the connect partner API on behalf of the user.
- The Connect Partner API validates the token before responding to the request.
Example Authorization Request for Production
https://auth.partners.abcsupply.com/oauth2/ausvvp0xuwGKLenYy357/v1/authorize?client_id={client_id}
&response_type=code
&redirect_uri={app_redirect_uri}
&state={random_string}
&scope=pricing.read order.read order.write product.read account.read location.read offline_accessExample Token Request for Production
curl -Ss -X POST https://auth.partners.abcsupply.com/oauth2/ausvvp0xuwGKLenYy357/v1/token
-H 'Authorization: Basic {authorization_value}'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'grant_type=authorization_code
&redirect_uri={app_redirect_uri}
&code={code_returned_from_authorization_request}'Example Refresh Token Request for Production
curl -Ss -X POST https://auth.partners.abcsupply.com/oauth2/ausvvp0xuwGKLenYy357/v1/token
-H 'Authorization: Basic {authorization_value}'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'grant_type=refresh_token
&refresh_token={refresh_token_issued}'Available Scopes
Scope Name
Description
location.read
Allows access to the location API
product.read
Allows access to the products API
account.read
Allows access to the accounts API
pricing.read
Allows access to the pricing API
order.read
Allows access to the Order API (GET Endpoint)
order.write
Allows access to the Order API (POST Endpoint)
offline_access
Allows Refresh Token to be sent back by the token endpoint
Authorization Code with PKCE
At a high level, the flow has the following steps:
- Your application generates a code verifier followed by a code challenge. See Create the proof key for code exchange.
- Your app requests an authorization code from the authorization server (Okta). The request contains the generated code challenge.
- The auth server presents an authentication prompt to the user’s browser.
- The user signs in with their ABC Supply credentials and and provides consent.
- Okta redirects back to your application with an authorization code.
- Your application sends this code, along with the code verifier, to Okta. See Exchange the code for tokens.
- The authorization server evaluates the PKCE code.
- The authorization server returns an access token, and optionally a refresh token.
- Your app can now use these tokens to call the connect partner API on behalf of the user.
- The Connect Partner API validates the token before responding to the request.
Example Authorization Request for Production
https://auth.partners.abcsupply.com/oauth2/ausvvp0xuwGKLenYy357/v1/authorize?
&client_id={client_id}
&response_type=code
&redirect_uri={app_redirect_uri}
&state={random_string}
&scope=pricing.read order.read order.write product.read account.read location.read offline_access
&code_challenge={base_64_encoded_sha_256_of_code_verifier}
&code_challenge_method=S256Example Token Request for Production
curl -Ss -X POST https://auth.partners.abcsupply.com/oauth2/ausvvp0xuwGKLenYy357/v1/token
-H 'Authorization: Basic {authorization_value}'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'grant_type=authorization_code
&redirect_uri={app_redicrect_uri}
&code=p2vgMVEapP8NPyH6g5zd5m7Z03DeijNkadQFwJd5FGg
&code_verifier={random_string_generated_by_client}'Example Refresh Token Request for Production
curl -Ss -X POST https://auth.partners.abcsupply.com/oauth2/ausvvp0xuwGKLenYy357/v1/token
-H 'Authorization: Basic {authorization_value}'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'grant_type=refresh_token
&refresh_token={refresh_token_issued}'Available Scopes
Scope Name
Description
location.read
Allows access to the location API
product.read
Allows access to the products API
account.read
Allows access to the accounts API
pricing.read
Allows access to the pricing API
order.read
Allows access to the Order API (GET Endpoint)
order.write
Allows access to the Order API (POST Endpoint)
offline_access
Allows Refresh Token to be sent back by the token endpoint
Client Credentials
The Client Credentials flow is used when client applications request an access token on behalf of the application itself.
At a high level, the flow has the following steps:
- Your client application makes an authorization request to the authorization server using its client credentials.
- The authorization server responds with an access token if the request credentials are accurate.
- Your app uses the access token to make authorized requests to the resource server.
- The resource server validates the token before responding to the request.
The {authorization_value} in the request is the Base64 value of the client id and client secret provided during registration with ABC API, separated by a colon:
Base64(<client_id>:<client_secret>)
Example Token Request for Production
curl -Ss -X POST \
https://auth.partners.abcsupply.com/oauth2/ausvvp0xuwGKLenYy357/v1/token \
-H 'Authorization: Basic {authorization_value}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=location.read product.read notification.read notification.write'Note: There is no authorization or refresh token call with the client_credentials flow.
Available Scopes
Scope Name
Description
location.read
Allows access to the location API
product.read
Allows access to the products API
notification.read
Allows access to the Notification API (GET endpoint)
notification.write
Allows access to the Notification API (POST/Delete endpoints)
Token Lifetimes
Access Tokens
Access tokens have a lifetime of 30 minutes. After 30 minutes, the refresh token (valid only for auth code flows) will need to be used to get a new access token and new refresh token.
Refresh Tokens
Refresh tokens have an infinite lifetime as long as they continue to be refreshed. If 7 days pass without the refresh token being used, the user will have to go through the authorization flow again to gain a new access and refresh token.