Breadcrumbs

API keys


Path to function: Management > API keys

On this page, create and manage keys to use with the OpenAthens REST API, including the API connector for local authentication and add-on options such as Fetching statistics reports via the API.

Permissions

An API key has one of three permission levels, enabling or restricting what it can do:

Authentication API

  • CAN: use with the API connector

  • CANNOT: create or manage OpenAthens accounts

  • CANNOT: access reports API

Reports API

This appears only if the function is enabled for your organisation (talk to your account manager in the first instance)

  • CAN: use with the reports API

  • CANNOT: create or manage OpenAthens accounts or any other function

  • CANNOT: use with the API connector

Full access

Other permission levels may be added in future.

Create a new key

  1. (Optional.) To create a key for a specific sub-organisation, switch into the sub-organisation before you begin.

  2. Go to Management > API keys. This page displays a list of current keys.

    Main API keys page. It shows a list of current keys and a 'Create' button. There is one key in the list, called 'test'.

  3. Press Create. The page loads a form for creating a new key

    API keys page, showing a form for creating a new key. There is a text field called 'Name' (marked as mandatory), followed by a choice of permissions - 'Authentication API' (selected), 'Reports API' and 'Full access'. There is also a field called 'Key', which is not editable and reads 'Key will be generated on save'. Finally, there are 'Save' and 'Cancel' buttons.

  4. In the Name field, give the key a name that describes its purpose.

  5. Select the appropriate permission level for the key: Authentication API, Reports API or Full access.

  6. Press Save.

The new key is generated and displayed in the list. The list shows the name of the key, the value of the key, and the date on which the key expires.

Main API key page, showing the list of current keys. The list now includes two keys, 'new key' and 'test'. Each listing shows the name of the key, an expiry date, the key itself (a long string of letters and numbers) and a 'copy' button.

To copy the value of the key, press Copy .

Edit a key

You can change the name or permission level of an existing key. You cannot edit the key’s value or expiry date.

  1. Go to Management > API keys.

  2. In the list, hover over the key you want to edit. Edit and Remove buttons appear.

    An example key called 'test', showing options to 'Edit' and 'Remove'.

  3. Press Edit.

    Listing for an existing key, followed by a form for editing the details of the key. The 'Name' field is set to 'New name'. 'Permissions' is set to 'Full access'. The 'Key' field, containing the automatically generated key value, is not editable. At the bottom of the form are 'Save' and 'Cancel' buttons.

  4. Change the name and/or permissions of the key.

  5. Press Save.

Delete a key

  1. Go to Management > API keys.

  2. In the list, hover over the key you want to edit. Edit and Remove buttons appear.

    An example key called 'test', showing options to 'Edit' and 'Remove'.

  3. Press Remove. A dialog opens, asking you to confirm the action.

    Dialog box that reads, 'Delete API key 'test'. If you continue, this will stop access for all applications currently using it.' There is a checkbox labeled 'I confirm I wish to continue', followed by 'Delete' and 'Cancel' buttons.

  4. Tick I confirm I wish to continue and press Delete.

Expiring keys

Each key has an automatically generated expiry date, which is displayed in the list of your current keys. On that date, the key will stop working.

Listing for an API key called 'test'. Beside the name of the key is its expiry date, 9 July 2028.

Before a key expires, you should generate a replacement key and arrange with your technical team to update relevant code in your API client.

OpenAthens sends a notification email 30 days before a key is due to expire, and continues to send regular notifications up to the expiry date. These emails are sent to all administrators of the organisation or sub-organisation to which the key belongs.

Anything to watch out for?

When a key expires or is removed, any application still using that key will receive API errors stating that its credentials are invalid. The application will not be able to interact with OpenAthens until it is updated with an active key.