# Authentication

All API endpoints (except `/health`, `/metrics`, and `POST /credentials`) require authentication via API key and secret headers.

## Headers

```
X-Api-Key:    ak_...
X-Api-Secret: sk_...
```

Both headers must be present on every authenticated request.

## How Authentication Works

1. Your request arrives with `X-Api-Key` and `X-Api-Secret`
2. The system validates the credentials using a high-performance multi-level cache
3. If valid, the request proceeds; if invalid, you receive HTTP 401

The credential validation is extremely fast. After the first successful authentication, subsequent requests with the same credentials are served from cache with near-zero overhead.

### Cache Behavior

Authenticated credentials are cached for up to **5 minutes**. This means:

* After revoking a credential, it may remain valid for up to 5 minutes
* No manual cache invalidation is needed — it expires naturally

## Obtaining Credentials

Credentials are generated through the vendor Console. The process is:

1. Generate an API key pair in the Console
2. Register the credentials on your ledger instance via `POST /credentials`
3. Use the credentials in all API calls

See [Credential Management](/docs/console/credential-management.md) for the full workflow.

## Multiple Credentials

You can have multiple active API key pairs. This allows:

* Rotating credentials without downtime
* Different keys for different environments or services
* Revoking compromised keys without affecting others

## Error Responses

| HTTP | Code           | Cause                                           |
| ---- | -------------- | ----------------------------------------------- |
| 401  | `UNAUTHORIZED` | Missing headers, invalid key, or invalid secret |

{% hint style="info" %}
The system distinguishes between authentication failures and database connectivity issues. A database error during credential lookup will never return 401 — it returns 500 to prevent false negatives.
{% endhint %}

## Security

* API secrets are **never stored in plain text** — only a cryptographic hash is persisted
* Secrets are derived using HMAC — they are not random strings
* The derivation mechanism ensures that only the vendor can produce valid credential pairs
* The `POST /credentials` endpoint validates the derivation before accepting — you cannot register arbitrary key/secret pairs


---

# Agent Instructions: 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:

```
GET https://entrytarget.gitbook.io/docs/api-reference/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.