Authentication and authorization

Use workspace-scoped bearer keys and explicit resource permissions.

Bearer API keys

Financial-data and reporting operations use server-to-server API keys bound to exactly one workspace, institution tenant, and environment. Healthcheck and service status are public read-only exceptions and require no API key.

Authorization: Bearer <AMLOK_API_KEY>
Accept: application/json

Use HTTPS. Keep credentials in your secret manager and load them on the server. Never put keys in a query string, browser bundle, analytics event, error report, or shared Postman export.

Your account manager provides client portal access information and environment details. Authorized administrators create API keys in the client portal, choosing the workspace, environment and permitted scopes. Manage expiry, revocation and rotation there. Authenticate server-side requests with your portal-created API key.

Authorization has several layers

Check	What it controls
Environment	A sandbox credential must not authorize production data.
Institution and workspace	Every resource and linked ID must belong to the one workspace bound to the key.
Endpoint scope	The operation requires its documented scope.
Product and provider entitlement	The institution must be entitled to the requested product and source.
Subject consent and purpose	Data collection and use must remain within recorded authorization.
Field entitlement	Sensitive fields can require additional permissions and purpose checks.

Caller-supplied tenant_id or workspace_id values cannot select another workspace. The API derives the workspace and institution from the key. Every subject, document, manifest, baseline, and webhook destination must belong to that workspace. Use a separately provisioned key for another workspace.

Read access does not authorize borrower communications, funding, filings, or changes to credit limits. AMLOK provides assessment results and risk alerts to your institution. Borrower outreach, collections, and intervention remain in your institution’s own systems. Credit access is reporting-only. No customer wallet or payment-setting endpoints are exposed. The client portal manages payment methods, top-up settings, and cancellation. Enterprise clients can also request cancellation through their dedicated account manager. Cancellation is available at any time without notice, with an immediate stop to processing, usage deductions, and upcoming top-ups. Full closure is at the end of the request month with an immediate refund of all unused credits to the saved portal bank account. Deletion follows month closure and generation of final information. Report generation and downloads do not change credits.

Scope reference

Scopes are API permissions. They are not OAuth claims or evidence that a provider grants all requested data.

Scope	Operations	Example
accounting:read	20	List ledger accounts
audit:read	2	List audit events
banking:read	10	List bank accounts
billing:export	4	Create billing report
billing:read	18	Retrieve current billing snapshot
commerce:read	8	List counterparties
connections:read	5	List connections
connections:write	4	Create connection
consent:read	2	List consents
consent:write	2	Create consent
documents:read	3	List documents
documents:write	1	Upload document
identity:read	14	List businesses
identity:verify	1	Start verification
identity:write	3	Create business
inventory:read	16	List products
lending:read	18	List applications
lending:write	1	Create application
liens:read	6	List lien searches
liens:search	1	Start lien search
monitoring:read	6	List monitors
monitoring:write	2	Create monitor
operations:read	2	List requirements
payments:read	12	List merchant accounts
platform:read	7	List reconciliation links
risk:calculate	1	Calculate attributes
risk:read	11	List attributes
webhooks:read	4	List webhook endpoints
webhooks:write	2	Create webhook endpoint
workflows:execute	2	Start workflow run
workflows:read	2	List workflow runs

Authentication failures

• 401 unauthenticated: missing, invalid, expired, or incorrect-environment credential. Stop retrying until credentials are corrected.
• 403 forbidden: the key is authenticated but lacks the necessary scope or entitlement.
• 404 not_found: an ID is missing or not visible to this institution. Do not probe IDs from other tenants.

Credential rotation

When your environment supports overlapping keys, provision a replacement, update consumers, verify traffic uses it, and revoke the old key through the agreed administration process. If overlap is unavailable, coordinate a cutover. Never infer a rotation endpoint from this guide.

Webhook signing secrets are separate from API keys. Store each secret with its destination and environment. The registration response returns a new signing secret only once; list responses omit it.