> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/document-ai/developer-documentation/getting-started/authentication.md).

# Authentication

Document AI authenticates API requests with an account API key, sent as a header. There is no OAuth flow, no token exchange, and no session to maintain — you create a key in the portal and send it with every call.

```bash
curl "https://api-docai-uat.uptiq.ai/document/supported-file-types" \
  -H "X-Api-Key: $DOCAI_API_KEY"
```

The key identifies the **account**, not the person who created it. Work done with a key is attributed to the account and draws on its credit balance, so treat a key as a service credential rather than a user credential.

### Creating a key

Keys are created in the portal, not through the API.

1. Sign in as **Owner** or **Admin**. Member and Viewer cannot see the API Keys screen at all.
2. Go to **Settings → API Keys**.
3. Click **Create API Key**.
4. Give it a **Name**, an optional **Description**, and an optional **Expires In (Days)**.
5. Copy the key from the confirmation dialog.

{% hint style="danger" %}
The key is displayed **once**, at creation. There is no way to retrieve it afterwards — if you lose it, revoke it and create another. The dialog labels the value "Key Prefix" even though it is the entire key.
{% endhint %}

Set an expiry unless you have a reason not to. A key with no expiry is valid until someone remembers to revoke it.

See [User Management](/document-ai/guides-1/user-management.md) for the roles that can manage keys, and for the rest of the account settings.

### Which endpoints need a key

Thirteen of the fourteen operations require the header. One does not:

| Operation                     | Key required                     |
| ----------------------------- | -------------------------------- |
| `GET /listSupportedDocuments` | **No** — this endpoint is public |
| Everything else               | Yes                              |

{% hint style="warning" %}
Do not infer that a whole group is public. `GET /document/supported-file-types` sits in the same [Utility](/document-ai/developer-documentation/integration-guides/utility.md) group as the public endpoint and **does** require a key.
{% endhint %}

The public endpoint is useful as a connectivity check, because a failure tells you something about the network rather than about your credentials.

### Storing the key

Keep the key out of source control, out of client-side code, and out of screenshots. Every example in these pages reads it from an environment variable:

```bash
export DOCAI_API_KEY='ak_…'
```

Because the key carries account-wide authority and cannot be scoped down, a key that leaks should be revoked immediately in **Settings → API Keys** rather than rotated on a schedule.

### What a missing or invalid key looks like

```
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"message":"Authentication required","status":"error","timestamp":"2026-07-29T03:00:11.034942+00:00"}
```

The same `401` covers a missing header, a malformed key, a revoked key, and an expired key — the response does not distinguish them. If a key that used to work stops working, check its expiry and revocation state in the portal before looking anywhere else.

{% hint style="info" %}
Authentication is evaluated **before** the request body is validated. A request with both a bad key and a malformed body returns `401`, not `400` — so fix authentication first, then worry about the payload.
{% endhint %}

### A note on the published spec

The OpenAPI document served at `/openapi.json` declares three security schemes — `ApiKeyAuth` (`X-Api-Key`), an `AccountId` header, and JWT `BearerAuth` — but then sets an empty top-level `security` requirement, which formally asserts that every operation is public.

**That assertion is wrong**, and these pages document the live behaviour instead. Practical consequence: a client generated straight from the spec will omit authentication and fail with `401` on its first call. Add the header yourself. Of the three schemes, `X-Api-Key` is the one to use — it is the only one the portal's own API console offers.

### Related pages

* [User Management](/document-ai/guides-1/user-management.md) — roles, account settings, and where keys live in the portal.
* [Errors](/document-ai/developer-documentation/getting-started/errors.md) — `401` in the context of the other status codes.
* [API Reference](https://gitlab.com/uptiq-inc-enterprise/development/documentation/uptiq-solutions-docs/-/tree/main/doc-ai/document-ai-1/api-reference/README.md) — the base URL and the operation groups.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.uptiq.ai/document-ai/developer-documentation/getting-started/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.