Authentication

The Open Ledger API uses JWT tokens to authenticate requests. You must include an authentication token with every API request.

API Keys and Token Generation

API keys are used to generate JWT tokens for authenticating requests to the Open Ledger API. Each account can have multiple API keys for different environments and purposes.

Obtaining API Keys

To get your API keys, please contact our team to request API access. Our team will set up an account for you and provide the necessary credentials.

Generating a JWT entity Token

To generate a JWT entity token, make a POST request to the token generation endpoint:

1
POST /v1/entities/auth/generate-token
2
Content-Type: application/json
3
4
{
5
  "developerId": "your-developer-id",
6
  "apiKey": "your-api-key",
7
  "entityId": "your-entity-id"
8
}

This endpoint returns a JWT token that you’ll use for subsequent API requests:

1
{
2
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
3
  "token_type": "Bearer",
4
  "expires_in": 3600
5
}

Authentication Methods

Bearer Token Authentication

All API requests must include the JWT token in the Authorization header:

1
Authorization: Bearer YOUR_JWT_TOKEN

Example request using bearer token authentication:

$
curl https://api.openledger.com/v1/transactions \
>
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6..." \
>
  -H "Content-Type: application/json"

Entity Context

Many API endpoints require you to specify which entity’s data you’re working with. You can provide the entity ID as a query parameter:

1
?entityId=entity_12345

Entity-Scoped tokens

You’ll likely want to generate entity-scoped tokens for your users to be able to access only their own entity’s data

1
POST /v1/entities/auth/generate-token
2
Content-Type: application/json
3
4
{
5
  "developerId": "your-developer-id",
6
  "apiKey": "your-api-key",
7
  "entityId": "your-entity-id"
8
}

Using Entity Access Tokens with OpenLedgerProvider

When using the OpenLedgerProvider in your React application, you can authenticate using an entity access token directly instead of developer credentials:

1
<OpenLedgerProvider
2
  entityId="your-entity-id"
3
  accessToken={{
4
    access_token: "your-entity-access-token",
5
    token_type: "Bearer",
6
    expires_in: 100 * 365 * 24 * 3600,
7
    expires_at: new Date(Date.now() + 100 * 365 * 24 * 3600 * 1000),
8
  }}
9
  environment="development"
10
  apiUrl="your-api-url"
11
  theme={{
12
    primary: { hex: "#511320" }, // CRANBERRY
13
    accent: { hex: "#511320" }, // CRANBERRY
14
    background: { hex: "#FFFFFF" }, // WHITE
15
    text: { hex: "#511320" }, // CRANBERRY for text
16
    secondary: { hex: "#7D4955" }, // Lighter CRANBERRY shade
17
    negative: { hex: "#B22222" }, // A red that works with this palette
18
  }}
19
>
20
  <App />
21
</OpenLedgerProvider>

The accessToken prop accepts an object with the following properties:

Using this method eliminates the need to provide developerId and developerSecret props.

Authentication Errors

If your authentication is invalid or expired, the API will return a 401 Unauthorized response:

1
{
2
  "error": {
3
    "message": "Authentication credentials are invalid or expired"
4
  }
5
}

If you’re missing the required entity context, the API will return a 400 Bad Request response:

1
{
2
  "error": {
3
    "message": "Required parameter entityId is missing"
4
  }
5
}

Sandbox Environment

For development and testing, you can use our sandbox environment. To set up a sandbox environment with test data, use the sandbox endpoint:

1
POST /v1/sandbox
2
Content-Type: application/json
3
4
{
5
  "name": "Test User",
6
  "api_key": "your_api_key",
7
  "industry": "Fintech",
8
  "preferences": {
9
    "currency": "USD",
10
    "timezone": "UTC",
11
    "locale": "en"
12
  }
13
}

This will create a new sandbox environment including a developer account, entity, ledger structure, and Plaid sandbox bank connections. It will also return a JWT token for API access.

Security Best Practices

1. Store API keys securely: Never hardcode API keys in your application code or expose them in client-side JavaScript.

2. Use environment variables: Store your API keys as environment variables rather than in your application code.

3. Implement secure token storage: Store JWT tokens securely, especially in browser environments.

4. Monitor API usage: Regularly review your API logs to detect any unauthorized or suspicious activity.

5. Use HTTPS: Always use HTTPS for API requests to ensure encrypted communication.

6. Set short token lifetimes: Request new tokens periodically to limit the impact of token exposure.

Need Help?

If you need assistance with API authentication or have any questions about accessing our API, please contact our support team.