Authentication

Authentication summary

All API endpoints require authentication via HTTP headers. The table below shows which headers each endpoint requires.

Endpoint	Required headers
POST /v3/text	app_id + app_key (or app_token)
POST /v3/pdf	app_id + app_key
POST /v3/strokes	app_id + app_key (or app_token + strokes_session_id)
POST /v3/batch	app_id + app_key
POST /v3/converter	app_id + app_key
POST /v3/app-tokens	app_key only
GET /v3/ocr-results	app_key only
GET /v3/pdf-results	app_key only
GET /v3/ocr-usage	app_id + app_key
GET /v3/batch/{id}	app_id + app_key
GET /v3/pdf/{id}	app_id + app_key
GET /v3/converter/{id}	app_id + app_key

Using server side API keys

{
  "app_id": "APP_ID",
  "app_key": "APP_KEY"
}

Every MathpixOCR server side request should include two headers: app_id to identify your application and app_key to authorize access to the service. You can find your API key on your organization page at https://console.mathpix.com.

warning

Never include your API keys inside client side code. Such API keys can easily be stolen by hackers by inspecting the app binary. If you want to make direct requests from client side code to the API, use app tokens, described below.

Using client side app tokens

To get a temporary app_token, do the following:

cURL

curl -X POST https://api.mathpix.com/v3/app-tokens -H 'app_key: APP_KEY'

Python

import requests
url = "https://api.mathpix.com/v3/app-tokens"
headers = {
    "app_key": "APP_KEY"
}
response = requests.post(url, headers=headers)
print(response.json())

TypeScript

const response = await fetch("https://api.mathpix.com/v3/app-tokens", {
  method: "POST",
  headers: {
    app_key: "APP_KEY",
  },
});
const result = await response.json();
console.log(JSON.stringify(result, null, 2));

Java

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mathpix.com/v3/app-tokens"))
    .header("app_key", "APP_KEY")
    .POST(HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

This then returns an app_token value which can be used as an app_token header to authenticate requests:

{
  "app_token": "token_e06840c31fbfd28c2aba38207e417c4e",
  "app_token_expires_at": 1649699265744
}

You can also create short lived client side tokens to make requests from clients (for example mobile apps) directly to Mathpix OCR servers. This reduces the need for customers to proxy their requests through their server to secure the requests. As such, it avoids an additional network hop, resulting in improved latency.

To get a temporary app token on your server to hand off to a client, use your API key to make a request to:

POST v3/app-tokens

The app_token will last for 5 minutes, after which requests will return HTTP status 401 (unauthorized). In such cases, the client can request an additional app token. Requests to create app tokens are free of charge.

With app_token, you only need a single authenticated route on your servers to get an app_token for your user. This means you do not need to worry about proxying image requests to our servers.

We have designed app tokens for individual image and digital ink requests (strokes) only. As such, app tokens have the following limitations when compared to API keys:

• cannot access PDF functionality
• cannot access historical data
• cannot access account admin data
• cannot make batch / async requests

note

The app tokens feature is in beta and is being actively developed.

Request parameters

include_strokes_session_id boolean (optional)

Return a strokes_session_id value that can be used for live update drawing, see v3/strokes for more info

expires number (seconds) (optional), default value is 300 seconds

Specifies how long the app_token will last. Values can range from 30 - 43200 seconds (12 hours) for an app_token and from 30 - 300 seconds (5 minutes) for a request with include_strokes_session_id.

Response parameters

app_token string

App token to be used in headers of v3/text, v3/latex, or v3/strokes requests

strokes_session_id string (optional)

if requested via, include_strokes_session_id, you can use this value to take advantage of our live digital ink pricing and SDKs, see v3/strokes

app_token_expires_at number

Unix timestamp in milliseconds specifying when the app_token will expire