---
title: "Authentication"
description: "Authenticate v1 API requests with an account API key in the x-api-key header or as an Authorization bearer token."
url: https://markitdown.ai/docs/authentication
updated: 2026-09-28
source: markitdown.ai
---

# Authentication

> Authenticate v1 API requests with an account API key in the x-api-key header or as an Authorization bearer token.

## API keys

Create a key in the dashboard under Settings → Developers — the account needs an active Lite, Pro, or Max subscription to create one. The full key (it starts with `mdai_`) is shown once; store it in a secret manager. Send it on every request in the `x-api-key` header. `Authorization: Bearer mdai_…` is accepted as an equivalent.

**Verify a key — read your credit balance**

```bash
curl https://api.markitdown.ai/v1/usage \
  -H "x-api-key: mdai_…"
```

## What a key can call

- Keys created in the dashboard have full access to the v1 API of your account by default. Scopes, when a key is restricted to them, are `read` (every GET and `/estimate`), `convert` (submit, retry, delete), and `webhooks` (manage endpoints).
- Keys work on `/v1/*` only. Calling a non-v1 path with a key returns `403 forbidden`.
- Keys cannot create or revoke other keys, and cannot reach billing or account settings; those stay in the signed-in dashboard.
- Every call made with a key counts toward your plan's credits and rate limit. Requests are attributed to the key, so you can tell which service created a conversion from its activity log entry in the dashboard.

## What header do I send?

Send `x-api-key: mdai_…` on every request. If your HTTP client or proxy only forwards the `Authorization` header, send `Authorization: Bearer mdai_…` instead; both resolve to the same key. A missing, revoked, or expired key returns `401 unauthorized` as `application/problem+json`. Never ship a key in browser code or a mobile app: anyone who reads it can spend your credits until you revoke it.

## How do I verify a key before converting?

Call `GET /v1/usage` with the key. A 200 response returns your plan, credit balance, monthly quota, and the next reset time without spending credits, which makes it a good start-up check for a worker or a CI job. A 401 means the key is wrong, revoked, or expired; create a new one in Settings → Developers. A 403 with `subscription_required` means the account has no active subscription. `GET /v1/formats` is another free call that also returns the `name` catalog and your plan's page and file-size limits.

## Related

- [Introduction](https://markitdown.ai/docs/introduction)
- [Quickstart](https://markitdown.ai/docs/quickstart)
- [Introduction](https://markitdown.ai/docs)
- [Document Conversion APIs](https://markitdown.ai/developers)