Authentication

Use your personal API key in the X-API-Key header for processing requests and MCP calls. Signed result links carry their own limited download authorization.

Scope of an API key

An API key covers the PDF upload service (/api/v1/upload-service/*) and the MCP endpoint (/mcp). It remains bound to the same Accessful user. Creating a signed result link requires this key; opening that short-lived link in a browser does not. Treat the signed URL as a secret with access to one result version.

Create an API key

The normal way to obtain a key is the Accessful portal: sign in, open API keys, and create one. The key is shown once at creation — copy it immediately. We store only a hash, so we can never display it again.

A key looks like this:

ak_oCe4cm015zL8vCbBne_wUZDcM6G1RWqD7Ekc2944EAA

• Prefix ak_ followed by 43 URL-safe characters.
• You can hold up to 10 active keys per account.
• A key can optionally carry an expiry date; revoke it any time from the portal.

Caution

Treat the key like a password. It is bound to your account and can upload, download, and permanently delete your cases. Never embed it in client-side code you ship to end users.

Manage keys programmatically (optional)

If you automate key rotation, the key-management endpoints live under /api/v1/auth/api-keys and require an OAuth2 bearer token from your portal login (Authorization: Bearer <jwt>) — not an API key:

Method & path	Purpose
POST /api/v1/auth/api-keys	Create a key — response contains the plaintext once
GET /api/v1/auth/api-keys	List your keys (values masked)
POST /api/v1/auth/api-keys/{id}/revoke	Revoke a key
DELETE /api/v1/auth/api-keys/{id}	Delete a key

Send the key on requests

Add X-API-Key to processing and MCP calls. Signed-link downloads need no API key:

curl

curl https://api.accessful.de/api/v1/upload-service/job-status/<caseId> \
  -H "X-API-Key: ak_your_key_here"

Node.js

await fetch(`https://api.accessful.de/api/v1/upload-service/job-status/${caseId}`, {
  headers: { 'X-API-Key': process.env.ACCESSFUL_API_KEY },
});

Java

HttpRequest.newBuilder()
    .uri(URI.create("https://api.accessful.de/api/v1/upload-service/job-status/" + caseId))
    .header("X-API-Key", System.getenv("ACCESSFUL_API_KEY"))
    .GET().build();

Verify your key

Smoke-test a key by asking for a random, non-existent case. A working key returns 404 (the case doesn’t exist) — not 401.

1. Send a status request with a throwaway case ID:

   curl -i https://api.accessful.de/api/v1/upload-service/job-status/00000000-0000-0000-0000-000000000000 \
     -H "X-API-Key: ak_your_key_here"

2. Read the status line:

   • 404 Not Found → your key is accepted. ✅
   • 401 Unauthorized → the key is missing, malformed, or revoked.

Auth errors

The following applies to the REST API. For MCP connection errors and tool errors, see MCP integration.

Status	Meaning
401 Unauthorized	No key, malformed key, or a revoked/expired key.
403 Forbidden	The key is valid but lacks permission for that action.

A missing or invalid key (401) is rejected at the gateway, before the request reaches the application — so a 401 never carries a Problem Details body. Rely on the status code. A 403 comes from the application itself and carries a Problem Details body, like other application-level errors.