API keys
An API key is how your systems authenticate to the OCR, Prep, NLP and Extract APIs. Keys belong to your organization, and the work done with them is billed to your organization.
Creating a key
Anyone in your organization can create a key on the platform. You choose:
- A label, so the key can be recognised later, for example
claims pipeline. - Scopes: the APIs the key may call. See below.
- How long it lasts, up to one year. If you do not choose, it lasts one year.
The key is shown once, when it is created. emtelligent stores only a hash of it, so it cannot be shown again. Store it in your secret manager straight away. If it is lost, create a new key and revoke the old one.
Keys start with sk-emt-. Secret-scanning tools can recognise that prefix in a
repository or a log.
Scopes
A scope says which API a key may call. Give a key a scope for each API your own code calls, and no others.
Some APIs use others internally: the Prep API uses the OCR API, and the Extract
API runs whichever pipelines a job needs. Those internal calls are authorized by
the call you made. A key with only extract:process runs a complete Extract
job, and is not separately billed for the work the Extract API does on your
behalf.
Using a key
Each API’s quickstart shows where to send the key:
Keep keys out of source code. Read them from the environment or a secret manager, as the quickstarts do.
Expiry
Every key has an expiry date. Before a key expires, the platform emails your organization’s owners, and the person who created the key if they are still a member, 30 days and 7 days beforehand. Create the replacement, deploy it, then revoke the old key, so there is no gap.
Revoking a key
Revoke a key as soon as it may have leaked, or when the system using it is retired. A revoked key stops working within a minute.
Anyone can revoke the keys they created. Owners and admins can revoke any key in the organization. When a member is removed, the keys they created can be revoked at the same time. See Accounts and sign-in.
Seeing what a key has done
Owners and admins can see usage broken down by credential, so the question “this key may have leaked: what has it been doing?” has an answer. See Billing and usage.
When a key is refused
A valid key is refused when your organization cannot currently be served: its credit has run out, the terms of service are waiting to be accepted, or emtelligent has placed a hold on the account. The platform shows which, and what to do about it. See Billing and usage and Terms and data handling.