Skip to content

Generate API Keys

Create an API Key

API keys are created in the administration screen of your Atfinity application. This means you need at least admin rights for Atfinity to create and manage API Keys.

The admin area is accessible by clicking on the shield icon in the lower left corner of the app. Once there, click on API Keys in the menu’s Integrations section.

Next, click 'Create API Key'. This screen will pop up:

Enter a name for your API Key and tick the scopes it needs, then click 'Create API-Key'.

Next, you will see a screen with the API Key that was created in bold. Be sure to copy it, so you can store and use it to authenticate yourself when making requests to the Atfinity API.

You can create an unlimited number of API Keys. In the API Keys overview, click ‘Revoke’ to delete keys you no longer need.

Choose the scopes

Info

New in Atfinity 18.

A key reaches only what its scopes cover, and a request outside them is refused with 403 Forbidden naming the scope it lacks.

  • cases:read and cases:write: cases, instances, values, proofs, documents, booklets, comments, wizards and the files under Logs & Files
  • configuration:read and configuration:write: the configuration, including its draft cases, importing it and putting it live, and webhooks, integrations, data sources, custom APIs, the tenant settings and the AI usage
  • users:read and users:write: users, roles and groups, and the user access log and admin log

A request that only reads, such as a GET or a download, needs the read scope, and any other request needs the write scope. The write scope does not include the read scope, so tick both for a key that has to do both. Fetching the file of a download or export that runs in the background needs the same scopes as starting it, such as cases:read for a booklet or configuration:write for a configuration export. A download or export from a draft case is started with the configuration scope but fetched with the cases scope, so it needs both. Exporting the configuration needs configuration:write. Exporting a configuration with user roles or user groups also needs users:read, and importing one needs users:write.

The Services page under Integrations, the Password, 2FA and Settings pages under Administration, and the administration settings of a configuration export hold the email server password, the SMS token and the settings for how users log in, so they need a users scope as well. Reading or exporting them needs users:read, and changing or importing them needs users:write. Only an administrator can export or import the administration settings, so a key acting as anyone else is refused. The admin log records changes in every area, so reading it needs cases:read, configuration:read and users:read.

No scope reaches API keys, OAuth clients and their redirect URIs, the External directory page with the LDAP, Single Sign On and SCIM settings, logging out, or anything only a meta admin may do. The scopes are fixed once the key exists, so create a new key to change them. Keys and OAuth clients created before Atfinity 18 have every scope, except an OAuth client that registered itself, which has the two configuration scopes.

An OAuth client takes scopes the same way. A token requested without a scope carries every scope of the client, and a request for a scope the client was not granted is refused with invalid_scope.

Use an API Key

To use an API Key in your communication with the Atfinity API, add it to the HTTP header of your request, with:

  • key: Api-Key
  • value: the bold value you copied when creating the key

As the key, use <Api-Key>.

As value, use the bold value you copied when creating the key.

Here’s an example of an authorization header:

’Authorization: Api-Key n58lzybi.1M2baTIHuRgPGbzdZC3Zch0b8VC2etL0’

To act as a user, send their email in a From header. The request can then do only what both the key's scopes and that user's permissions allow.