Skip to content

Managing API Keys

Managing API Keys#

API Keys let external applications call the Datameer API without a user logging in. Use them to:

  • trigger Jobs from an external scheduler or orchestrator, and check on their status
  • allow an external application to read Datameer's lineage events

API Keys are managed on the Admin page under "API Keys".

Who can manage API Keys

Only Datameer Admin users can create or revoke API Keys.

How API Keys work#

  • An API Key acts on behalf of the Admin user who created it. The user is recorded on the key and shown in the "Created by" column.
  • An API Key can only call the operations allowed by its permissions. Permissions are chosen when the key is created and cannot be changed afterwards.
  • An API Key expires one year after it is created. The expiry date is shown in the "Expires at" column. To keep an integration running, create a new key before the old one expires.
  • Datameer does not store the key itself, so it is shown only once, right after it is created. If you lose it, revoke it and create a new one.

Warning

Treat an API Key as a secure credential. Do not check it into source control or share it in chat or email.

Permissions#

Permission Allows the key to
Manage Jobs trigger a Job run, query the status of a Job run, and cancel a Job run
Ingest Events read the lineage events (OpenLineage) that Datameer emits about Job runs

Select only the permissions the application needs. For example:

  • An orchestrator that triggers Jobs needs Manage Jobs.
  • A data catalog or observability tool that collects lineage from Datameer needs Ingest Events.

Creating an API Key#

To create a new API Key:

  1. Open the Admin page and click on "API Keys". The page 'API Key Management' opens and lists the existing keys.

  2. Click on "New API Key". The dialog 'Create New API Key' opens.

  3. Enter a Name for the application that will use the key. Optionally, add a Description of up to 400 characters.

  4. Select the permissions the application needs: "Manage Jobs", "Ingest Events", or both.

  5. Confirm with "Create". The dialog 'API Key Created!' opens and shows the new key.

  6. Copy the key with the copy button and store it somewhere secure, such as your organization's secrets manager.

    Warning

    You will not be able to see the key again after you close this dialog.

Using an API Key#

Send the key in the Authorization header of each API request:

Authorization: Bearer <API_KEY>

For example, to trigger a Job run (requires Manage Jobs):

API_KEY=<API_KEY>
curl -X POST -H "Authorization: Bearer $API_KEY" \
  'https://<your-datameer-host>/api/op/TriggerJobRunApi' \
  -d '{ "definitionUid" : "<job-definition-uid>", "callbackUrl" : "<your-webhook-endpoint>", "skipChecks" : false }'

The response contains a statusUrl. Poll it with a GET request using the same Authorization header to follow the run. The API Trigger Setup and Help dialog for each Job has a ready-to-use script that already contains the Job's definitionUid.

Revoking an API Key#

Revoke a key when the application no longer needs it or if the key may have been exposed. Revoking takes effect immediately, and it cannot be undone.

To revoke an API Key:

  1. Open the Admin page and click on "API Keys".

  2. Open the more menu for the key and click on "Revoke". The dialog 'Revoke API Key' opens.

  3. Confirm by pressing and holding the "Revoke API Key" button. The key is revoked and the date is shown in the "Revoked at" column.

Revoked keys stay in the list for auditing purposes.