OAuth 2.0 for Third-party Authentication
This document explains how to implement OAuth 2.0 authorization to access MonroneyLabels. OAuth 2.0 allows your dealers to share specific data with your application while keeping their username and password secret.
You will use an OAuth client to send your dealers to an authorization page that looks like this:
After the dealer clicks "Authorize", they will be redirected back to your application and you will have an access code to decode VIN's on their behalf.
Step 1: Get a client ID and client secret
Contact us to get your new client_id and client_secret keys. You will also need to send us your website address and your redirect_uri. Your dealer will be redirected back to that URI after authorization.
Step 2: Send the dealer to the Oauth 2.0 endpoint URL
Our Oauth 2.0 endpoint is https://monroneylabels.com/oauth/authorize
If you are using an Oauth 2.0 client, generally that's all you need to build the request.
If you want to build the request manually, you will need to create a code challenge with PKCE. After you have the code_challenge and code_verifier, build the URL using the client_id, code_challenge, code_challenge_method, and redirect_uri. For scope send the value "read write". You may optionally send a state parameter.
Send the dealer to: https://api.monroneylabels.com//oauth_authorize?client_id={client_id}&code_challenge={code_challenge}&code_challenge_method={code_challenge_method}&redirect_uri={redirect_uri}&response_type=code&scope=read write
The dealer will see a page asking them to authorize or deny access for your app.
After clicking "Authorize", the dealer will be redirected back to your redirect URI. The authorization code you need will appear as a URL parameter named code. If you provided a state parameter, it will also be sent back to you as a URL parameter.
Step 3: Request an access token
Once you have the authorization code, make a POST request to /oauth/token to get an access token. You will send a grant_type of "authorization_code" along with the code, client_id, client_secret, redirect_uri, and code_verifier.
Upon successful authorization, you will get an access_token. You can now use the access_token to decode cars.
The refresh_token is only needed when the access-token expires. Since access-tokens don't expire, you will not need it.
Step 4: Access the VIN Decode API
Access the VIN Decode API and add an Authorization header, with the value of Bearer {access_token}. Do not send a single_access_token parameter.
HTTP Request
GET /cars/vin.json?car[vin]={vin}
HEADER Bearer {access_token}
Step 5: Refresh the Access Token
When the access_token expires, you can get another one without dealer authentication. Send a POST request to /oauth/token with your client_id, client_secret, and refresh_token. The grant_type will be "refresh_token".
If successful, you will receive a refreshed access_token.
