Authenticating with OAuth 2.0

The Altruist Public API uses OAuth 2.0 to authenticate and authorize API requests. Altruist supports the OAuth 2.0 authorization code flow, which involves obtaining an authorization code from the user and then exchanging that code for an access token that can be used to make API requests. Altruist also supports using refresh tokens to obtain new access tokens without requiring the user to re-authorize the application.

The Altruist Public API uses this method of authentication which is more secure than traditional username/password authentication because the user's credentials are never shared with the third-party application. Instead, the application receives a temporary access token that can be used to access the user's data for a limited amount of time. Additionally, users can revoke access at any time, making it easy to control which applications have access to their data.

The Altruist Public API allows authenticating with OAuth 2.0 using authorization code grants. Authorization is scoped to individual users (who may have different permissions from one another) rather than organizations.

Step 1: Get an Authorization Code

First of all, you should make sure that you've already received:
- client_id and client_secret from Altruist for Public API access.
- Approved user’s consent.
  Altruist will issue an authorization code and honor the redirect_uri which was set by Altruist’s partner during the user’s consent step.
- Get the access token for Altruist Public API access.
- Pass access token as code for Public APIs endpoints.
This step has the following base URLs for the respective environment:
- Production: https://oauth.altruist.com/;
- Sandbox: https://oauth.stage1.altruistnet.tech/.
Follow the step through the user’s consent flow, the code will be returned in the redirect URI after confirming the Altruist Integration as follows:
https://{redirect_uri}?code={authorization_code}

Suggested Example

A user clicks the Connect button, and makes a call to POST /api/oauth2/authorize with the following query parameters:
- client_id - Partner's client_id issued by Altruist;
- redirect_uri - Partner's website location.
- scope - Currently, we only support openid
- state - This parameter will be returned to the client app in the redirect_uri after completing the authorization process. Clients can use this to preserve the previous state of their application.
Sample request (Altruist Sandbox Environment)

<html>
  <body>
    <form
      method="POST"
      action="https://oauth.stage1.altruistnet.tech/api/oauth2/authorize?client_id=DUMMY_CLIENT&scope=openid&redirect_uri=DUMMY_REDIRECT_URI&state=DUMMY_STATE"
    >
      <button>Connect Altruist</button>
    </form>
  </body>
</html>

The Altruist's OAuth login page opens in the new browser tab.

Altruist users should enter the valid Altruist’s login credentials.
The user should see a confirmation page "Connect Altruist" on successful login.
Clicking on the Connect Altruist button will notify Altruist about the user’s consent for the given client_id and authorize the currently logged-in user’s access to the requesting partner.
OAuth 2.0 authorize request will issue an authorization code through the redirect URI and the user will return to the partner application based on the redirect_uri.

Step 2: Get an Access Token

Prerequisite: Get the authorization code

POST /altruist-open-api/oauth2/token

Make a call to POST /altruist-open-api/oauth2/token with:
- client_id - Altruist’s partner unique ID issued by Altruist;
- client_secret - Altruist’s partner secret key issued by Altruist;
- code - required when grant_type is authorization_code;
- refresh_token - required when grant_type is refresh_token;
- grant_type - authorization_code (to get access token from code), refresh_token (to get access token from refresh token);
- token_type - id.
If the request is successful, you will get a response body with the following:
- access_token - the access token (expires after 1 hour) to be used with APIs;
- refresh_token - the refresh token (expires after 30 days) to be used to generate a new access token after the previous token expires;
- expires_in - the token expiration time in seconds;
- token_type - the type of the token issued.

Steps 2 and 3 have the following base URLs for the respective environment:

Production: https://openapi.altruist.com/altruist-open-api/;
Sandbox: https://openapi.stage1.altruistnet.tech/altruist-open-api/.

Step 3: Use the Access Token

When you've got the access token, you can paste it into the API Authorization header as a bearer token.
This bearer token serves as an authorization mechanism and grants access to utilize all Altruist Public APIs.