OAuth

OAuth is an authorization framework that enables applications to obtain limited access to a user’s accounts and data. Using OAuth 2.0, Addepar can allow third-party applications to access a user’s Addepar data using their Addepar credentials.

Authorization Code Grant Flow

This section illustrates how the Authorization Code grant process works.

1. Your end-user will access the Addepar integration through your client application.

2. Your client application will send the user to the Addepar login modal using the
   authorization request URL, which includes your redirect URI.

3. Upon login, the user will be prompted to authorize Addepar scopes.

4. Once the user has authorized access to your client application, they will be sent back to the redirect URI from step 2, along with a unique authorization code in the URL.

5. The client application takes the authorization code it receives from Addepar and makes another request to the server. This request includes the OAuth client secret key. When the server sees a valid authorization code and client secret key, it responds with an access token that is valid for 60 minutes, and a refresh token that must be stored within your client application for subsequent requests.

6. At this point, the user is free to make requests to Addepar through your client application until their access token expires, which requires the stored refresh token and secret to request a new access token.

OAuth Client Setup

This section outlines what Addepar provides you and what you need to provide to get set up as an OAuth client.

Addepar provides the following:

• Client ID: a string. For example, this could be a firm's name.
• Client Secret: a 256-bit value converted to a hexadecimal string representation.
• The list of scopes that the client application can access once it's authorized.

The Client ID and Client Secret are used when the client application exchanges the authorization code for access and refresh tokens.

Provider of the client application must supply the following:

• Redirect URI: A URL within the client application that the OAuth server will redirect to upon a successful authorization. The client application should implement server-side logic to complete the OAuth handshake, i.e., an authorization code exchange for access and refresh tokens. Multiple redirect URLs are supported.
• Terms of Service URL.
• Privacy Terms URL.

Scopes

Request User Authorization

The example below shows a sample authorization URL. Your Addepar contact will provide you with the correct authorization URL to use for your integration or OAuth client.

Send Authorization Request: From a Developer's Perspective:

1. You'll start by constructing a URL as detailed in the table below. This will redirect the user to the URL to begin the authorization process.

🚧

The redirect URI must be ​URL encoded​.

2. Once the user has authorized the integration, they will be redirected back to the provided redirect URI along with the authorization code appended to the end.

3. You'll then fetch the authorization code from the incoming request URL and make the API request to gain access and refresh tokens with the provided authorization code.

❗️

The authorization code expires after 60 seconds. After 60 seconds the user will have to reauthorize against Addepar to generate another authorization code.

Send Authorization Request: From a User's Perspective:

1. The user starts the authorization process from a third party application where they will be redirected back to Addepar to login and authorize the integration.

2. Once the user logs in, they will select the appropriate firm. If they have access to only one firm, they will click Continue. If they have access to multiple firms, they will click Continue for the firm they want to set up the integration for.

3. They will then click Authorize to allow third-party integration to gain access to the appropriate scope(s).

4. After authorizing, the user will be redirected back to the third-party application along with the authorization code.

Request Access or Refresh Tokens

🚧

You can only make this request once per authorization code. Save the resulting refresh token in a secure location. The access_token is good for 60 minutes and can be renewed indefinitely with the refresh token.

Request Access

📘

To set up your OAuth client, reach out to your Addepar contact for assistance.

Using Postman or cURL, prepare an API request, as shown below.

Example:

curl --location --request POST 'https://examplefirm.addepar.com/api/public/oauth2/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'client_id=example' \
   --data-urlencode 'grant_type=authorization_code' \
   --data-urlencode 'redirect_uri=https://example.com/oauth/c' \
   --data-urlencode 'code=CAEQBRoQUHOKhNgeqAtSXCwkh54eYg' \
   --data-urlencode 'client_secret=VQ2b71RqtYIoj//enHEdALepvo5s7Huobbboo9KQMj8='

HTTP/1.1 200

{
  "access_token": "CAEQAhoQmsm3mdt09PhyG9qd_Xdrw",
  "refresh_token": "CAEQAxogfUvWFDfIDMBqSYVWp4m7A4-yLwUoCZ0svXwsrl7hKN8",
  "addepar_subdomain": "example",
  "addepar_firm": "2",
  "token_type": "bearer",
  "expires_in": 60
}

Response Codes

• 200 OK: Success
• 400 Bad Request: One of the request parameters was invalid or the authorization code was expired

Refresh Token

Using Postman or cURL, prepare an API request as shown below.

Example:

curl --location --request POST 'https://examplefirm.addepar.com/api/public/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=example' \
--data-urlencode 'grant_type=refresh_token \
--data-urlencode 'refresh_token=VONGFSZ4SG5R3KNZVYHT926I71VVTQ' \
--data-urlencode 'client_secret=VQ2b71RqtYIoj//enHEdALepvo5s7Huobbboo9KQMj8='

HTTP/1.1 200

{
  "access_token": "CAEQAhoQG4WaecpqShCPSOzjGt6u-A",
  "refresh_token": "CAEQAxogfUvWFDfIDMBqSYVWp4m7A4-yLwUoCZ0svXwsrl7hKN8",
   "addepar_subdomain": "example",
  "addepar_firm": "2",
  "token_type": "bearer",
  "expires_in": 60
}

Response Codes

• 200 OK: Success
• 400 Bad Request: One of the request parameters was invalid or the authorization code was expired

Example: Make a Request

After you've gained an access token, you can begin sending requests to the Addepar APIs. The Addepar API documentation provides all available details on each API endpoint.

Using a portfolio query as an example, prepare an API request using Postman or cURL, as shown below.

Example:

curl -X POST \
  https://api.addepar.com/api/v1/portfolio/query \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Addepar-Firm: `1' \
  -H 'Authorization: Bearer CAEQAhoQG4WaecpqShCPSOzjGt6u-A' \
  -d \
'{
  "data": {
    "type": "portfolio_query",
    "attributes": {
      "columns": ["value"],
      "groupings": [],
      "start_date": "2018-01-01",
      "end_date": "2019-01-01",
      "portfolio_type": "FIRM",
      "portfolio_id": 1
    }
  }
}'

HTTP/1.1 200

{
  "meta":{
    "columns":[
      {
        "key":"value",
        "display_name":"Value (USD)",
        "output_type":"Number",
        "currency":"USD"
      }
    ],
    "groupings":[
      
    ]
  },
  "data":{
    "type":"portfolio_views",
    "attributes":{
      "total":{
        "name":"Total",
        "columns":{
          "value":-760511.2500000002
        },
        "children":[
          
        ]
      }
    }
  },
  "included":[
    
  ]
}

Response Codes:

• 200 OK: Success
• 400 Bad Request: Improperly formatted query or lacking necessary data permissions
• 403 Forbidden: User lacks API permission or has not granted the appropriate scope