Authorization

To authorize and authenticate your requests, the backend needs to know about your API key. The API key needs to be provided in the HTTP request header field Authorization following the format Bearer <Your-API-Key>. If your API key was abcd1234, you would sent the value Bearer abcd1234 as the value of the Authorization headers for each of your requests.

Authorization: Bearer <Your-API-Key>

Command Line Example:

# curl -sSH 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.[…]' 'https://dev-brokerage.lemon.markets/v1/company' | jq
{
  "id": "ten_2••••••••••••••••••••••••••••••8",
  […]
}
# 

Request Tracing for Data Protection Logging

In order to allow requests to be traced back the the original cause, two more headers are required to access the API:

• LMG-Data-Privacy-Access-Principal
• LMG-Data-Privacy-Access-Justification

LMG-Data-Privacy-Access-Principal

Use the header LMG-Data-Privacy-Access-Principal to indicate the level of authorization granted by a customer. We recommend to use the following format for the header value:

{service_name}-{username}

This allows defining a list like the following to indicate the origin and principal of a request:

• api_production: This provides a way to indicate that a request comes from the production backend of your internal API. Example: Use a value like api_production-acc_01234 to indicate that the request was made by your API service on behalf of the authenticated user acc_01234.
• market_data: If you want to develop a component that caches market data for all users, you can send a value like market_data-none.

NOTE: These values will be logged and monitored. We strongly advise against using static strings like none, test or placeholder unless you can really not provide a principal.

LMG-Data-Privacy-Access-Justification

Use the header LMG-Data-Privacy-Access-Justification to indicate the reason for calling a specific endpoint. We recommend to use the following format for the header values:

{context}-{correlation ID/reference text}

The context can be represented by a list with different values like the following:

• app_usage: A category that can be used to indicate requests made as a result of the user performing a specific action in the app. Example: When the user opens the portfolio overview screen, you can indicate this using the header value app_usage-portfolio_screen.
• push_notification: You can define a category like this in order to mark requests you make in order to send push notifications. Example: When you receive a webhook message about a trade being executed, you can indicate it by using a header value like push_notification-trade_executed.
• customer_support: You can define a category like this in order to mark requests made as a result of customer support processes. Example: When a customer support representative processed a ticket, requests can have a value like customer_support-https://your-helpdesk-solution/ticket/12345.