API documentation
OAuth 2 documentation
Creating an App
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.
Redirect URIs
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.
Client ID and Secret
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.
Authorization
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.
Getting an Access Token
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
API flow papertrail-ai
Our github page includes more detail on accessing the papertrail-ai API. https://github.com/papertrail-ai/papertrail-ai