Before you can begin the OAuth process, you must first register a new app with Papertrail-ai. When registering a new app, you usually register basic information such as application name, website, a logo, etc. In addition, you must register a redirect URI to be used for redirecting users to for web server, browser-based, or mobile apps.

The service will only redirect users to a registered URI, which helps prevent some attacks. Any HTTP redirect URIs must be served via HTTPS. This helps prevent tokens from being intercepted during the authorization process.

After registering your app, you will receive a client ID and a client secret. The client ID is considered public information, and is used to build login URLs, or included in Javascript source code on a page. The client secret must be kept confidential.

The first step of OAuth 2 is to get authorization from the user. Authorization is granted through the interface provided by to the user.

OAuth 2 provides several "grant types" for different use cases. Papertrail makes use of the authorization code grant type.

Send user to:
https://www.papertrail-ai.com/api/authorize.php
response_type=code - Indicates that your server expects to receive an authorization code
client_id - The client ID you received when you first created the application
redirect_uri - Indicates the URI to return the user to after authorization is complete
scope - One or more scope values indicating which parts of the user's account you wish to access
state - A random string generated by your application, which you'll verify later The user sees the authorization prompt.

If the user clicks "Allow," the service redirects the user back to your site with an authorization code:
https://example-app.com/cb?code=AUTH_CODE_HERE&state=1234zyx
code - The server returns the authorization code in the query string
state - The server returns the same state value that you passed
You should first compare this state value to ensure it matches the one you started with. You can typically store the state value in a cookie or session, and compare it when the user comes back. This helps ensure your redirection endpoint isn't able to be tricked into attempting to exchange arbitrary authorization codes.

Your server exchanges the authorization code for an access token by making a POST request to the authorization server's token endpoint:

POST https://www.papertrail-ai.com/api/token.php
grant_type=authorization_code&
code=AUTH_CODE_HERE&
redirect_uri=REDIRECT_URI&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET
grant_type=authorization_code - The grant type for this flow is authorization_code
code=AUTH_CODE_HERE - This is the code you received in the query string
redirect_uri=REDIRECT_URI - Must be identical to the redirect URI provided in the original link
client_id=CLIENT_ID - The client ID you received when you first created the application
client_secret=CLIENT_SECRET - Since this request is made from server-side code, the secret is included

Our github page includes more detail on accessing the papertrail-ai API. https://github.com/papertrail-ai/papertrail-ai