Authentication & API keys
Authentication & API keys
DocLab accepts tenant-scoped API keys or API-audience bearer access tokens. The available key-management and licensing features depend on your deployment.
Authenticate a document request
Send one of these headers over HTTPS:
X-Api-Key: <your-tenant-api-key>
Authorization: Bearer <your-api-access-token>
Do not send both. An invalid bearer token does not fall back to an API key supplied alongside it.
| Permission | Operations |
|---|---|
documents.read |
Template inspection, capability discovery, production OpenAPI |
documents.generate |
Document generation, conversion, connector generation |
Bearer access tokens must target the DocLab API and pass issuer, audience, signature, expiration, tenant, and permission validation. Permissions come from scp or application roles as appropriate. A Microsoft sign-in ID token is not an API access token.
Manage keys in the workbench
Where self-service keys are enabled:
- Sign in with your organizational Microsoft account and open API Keys.
- Create a key for your licensed tenant. One active key is allowed per user, tenant, and product.
- Reveal, copy, or use your active key through the creator-only controls.
- Revoke the key when it is no longer needed. Replace a compromised key immediately.
The workspace gateway uses a delegated DocLab token: documents.read for read operations and additionally documents.generate for create, reveal, and revoke. It rejects anonymous callers, API-key authentication, and application-only tokens for key management. The server derives tenant and user identity; a browser-supplied tenant ID does not authorize access.
Secrets remain masked in lists and are held only in page memory when revealed. They are cleared on refresh, revoke, or navigation, not stored in browser persistent storage. Older hash-only keys may not be retrievable; replace them if their original secret is lost.
The older foundation used only configuration-backed keys. The later tenant-key integration adds self-service issuance and creator-only retrieval in configured deployments. Do not assume every API environment has that integration enabled.
Operator-issued keys
For deployments using configuration-backed keys, ask your API operator for an authorized key. Operators generate at least 32 random bytes and store only the SHA-256 hash with its tenant and permissions. Deliver the raw secret securely. Rotate by adding a replacement and removing the old entry after clients migrate.
Self-service cwdg_... keys require the licensing validator in the target API. A key issued by a hosted environment is not automatically accepted by a local API’s configured-key list.
Trials and usage
When the documented licensing integration and usage enforcement are enabled:
- An eligible tenant receives one 30-day trial, with 100 shared credits per UTC calendar month.
- Repeated sign-ins do not extend or restart a trial, renew an expired trial, or replace a paid license.
- Allocation is shared across the tenant’s users and credentials, not reset by creating a new key.
- Each admitted authenticated inspection, generation, or conversion consumes one credit, including operations that fail after admission.
- Capability checks, key management, anonymous demos, preview reads, and rejected authentication/admission do not consume document credits.
- A new UTC month resets monthly usage, not the trial expiry. Paid entitlements use their configured limits.
The API Keys page shows usage, remaining credits, expiry, and the next reset. Credit enforcement is separate from per-minute request throttling.
For the private-preview OAuth connector, connection checks and internal picker/schema lookups are credit-exempt; generation is metered. See Power Platform.
Protect credentials
Never put keys or access tokens in source control, URLs, logs, screenshots, or support requests. Keep server-to-server licensing credentials out of frontend configuration and client code.
Issued keys must be unrevoked, unexpired, and backed by an active entitlement. The documented validator has no positive validation cache, so subsequent validation observes revocation. Licensing outages fail closed with 503; expired/inactive entitlements return 403, and exhausted credits return 429.