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.

Token typescript

Tokens can be for developers, or for entities. Developer tokens are authorized to take action on behalf of any entity associated with their developer.

Generating a JWT developer Token

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

1
POST /v1/auth/tokens
2
Content-Type: application/json
3
4
{
5
  "apiKey": "your-api-key",
6
  "id": "your-developer-id",
7
  "userType": "developer"
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
  "apiKey": "your-api-key",
6
  "id": "your-entity-id",
7
  "userType": "entity"
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
    "code": "AUTHENTICATION_ERROR",
4
    "message": "Invalid authentication token"
5
  }
6
}

If you’re missing the Authorization header, the API will return a 401 Unauthorized response:

1
{
2
  "error": {
3
    "code": "AUTHENTICATION_ERROR", 
4
    "message": "Authorization header is required"
5
  }
6
}

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

1
{
2
  "error": {
3
    "code": "INVALID_API_KEY",
4
    "message": "API key is invalid or expired"
5
  }
6
}

If you’re trying to access a resource you don’t have permission for, the API will return a 403 Forbidden response:

1
{
2
  "error": {
3
    "code": "AUTHORIZATION_ERROR",
4
    "message": "Entity tokens cannot access developer routes"
5
  }
6
}

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.