Access & Authentication

All connections to the Addepar API must be authenticated through assigned permissions, generated key and secret pairs, and properly formatted requests. Addepar authenticates over HTTPS. If you need bearer token auth, see OAuth.

Overview

📘

Key security

Your API keys carry significant weight. Store key/secret combinations in a secure vault. Never share them in publicly accessible areas like GitHub, client-side code, or plaintext email.

Step 1: Assign API permissions

To manage API integrations, your Addepar user credentials must be permissioned for API access. This includes creating API keys, generating API access URLs, and accessing all data permissioned to the key holder.

To grant API access:

1. Click the product menu icon in the top-left corner, then select Firm Administration. In the left sidebar, click Users under User Permissions.
2. From the list of firm users, choose the individual whose permissions you want to set.
3. Click the Permissions tab.
4. Scroll down to API Access and select Create, edit, and delete.

Step 2: Create an API key

API access keys are the authentication credentials for the Addepar API. Each key is paired with a secret shared only with the user who creates it. Both are required to authenticate requests.

Each key/secret pair respects the tool and data permissions granted to the user who created it:

• All data you have permission to access (client portfolios and groups)
• All tool permissions assigned to you (view, create, update, delete clients, investments, groups, attributes, files, and user profiles)

📘

Third-party developers

To request an API key and secret, contact your firm administrator.

To create a key:

1. Click the product menu icon in the top-left corner, then select Firm Administration. Under Admin Tools, click API Access Key.

2. Click the + button in the rightmost corner of the table header.
3. Enter a description of the key (typically the name of the integration it supports).
4. Click Create.

5. Record the key and secret. Store the combination in a secure location.

Review key usage

To review API key usage, select "Display all access keys" in the API Access Key settings, then review the "last used on" date for each key.

Step 3: Format API requests

Addepar allows only authenticated requests. All requests must be made over HTTPS.

Constructing the auth credential:

1. Combine your API key and secret with a single colon: key_id:key_secret
2. Encode the combined string using Base64
3. Prepend Basic and a space to the result

Finding your firm ID:

• From the application URL: Your firm ID is in the URL path when signed in.
• From the API URL generator: In the Analysis Tool, click Export > "Generate API URL." Your firm ID is the addepar_firm= value.

Replace {firm} with the subdomain your firm uses to log into Addepar. For example, if your firm is Terra Bella Capital: https://terrabella.addepar.com/api/v1

Required headers for GET and DELETE:

curl -X GET "https://{firm}.addepar.com/api/v1/entities/1234" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

Required headers for POST and PATCH:

curl -X POST "https://{firm}.addepar.com/api/v1/entities" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "entities",
      "attributes": {
        "currency_factor": "USD",
        "model_type": "PERSON_NODE",
        "original_name": "New entity"
      }
    }
  }'

Data privacy best practices

• Store each key/secret combination in a secure vault. Guard it as you would any sensitive password.
• Create a different key for each integration. This protects existing integrations if a key is compromised and helps track who manages each integration.
• Create a separate user profile with appropriate permissions when sharing keys with third parties.
• Appoint a firm admin to monitor active API keys and delete obsolete ones.
• Never expose keys in GitHub, client-side code, or plaintext email.

📘

Related resources

• OAuth -- Bearer token authentication for third-party integrations.
• Rate Limiting -- Understand request limits and throttling behavior.
• Response Codes -- Common HTTP status codes returned by the API.