An API Key can be specified in .netrc/_netrc, provided to API functions, and used with external clients that support Basic authentication. Since a valid API Key provides complete access to your data and actions, it should be kept secret. API Keys have security benefits over passwords:
The API Key is a long, randomly generated token that provides an alternative authentication credential for use with APIs. A valid API Key provides complete access to your data and actions, so it should be kept secret.
Once enabled, a logged-in user can retrieve an API Key via username > External Tool Access:
Click Generate API Key to create one. In the popup, you can provide your own description of the usage of that key, which can help you later if you need to determine which key(s) may have expired. Click Generate API Key again.
Click the button to copy it to the clipboard. Important: the key itself will not be shown again and is not available for anyone to retrieve, including administrators. If you lose it, you will need to regenerate a new one.
Click Done at the bottom of the page. Your key with any description will now be listed.
You can then use this key in a .netrc/_netrc file or via clients that authenticate using Basic authentication. All access to the system will be subject to your authorization and logged with your user information.
If needed, you can generate multiple API Keys and use them in different contexts at the same time to provide the same access under your credentials.
To avoid embedding credentials into your code, you can use the API Key as a password within a .netrc/_netrc file. When doing so, the username is "apikey" (instead of your email address) and the password is the entire API Key. This is the recommended method of using an API Key; it is compatible with all LabKey client libraries.
machine localhost
login apikey
password the_long_string_api_key
Any API use via a LabKey client library will be able to access the server with your permissions, until the key expires or is terminated by an administrator.
If you see an error like one of these:
Error in handleError(response, haltOnError) :
HTTP request was unsuccessful. Status code = 401, Error message = User does not have permission to perform this operation.
labkey.exceptions.RequestAuthorizationError: '401: User does not have permission to perform this operation.'
Check to see if you are using an invalid API Key, either one that has expired, been revoked, or has additional characters (such as the "apikey|" prefix that was previously used with API Keys and is no longer used). The invalid key could be in your script or in the .netrc/_netrc file.
A site administrator can manage API Keys generated on the server using the APIKey query. Link to it from the top of the null username > External Tool Settings page.
You will see the keys that have been generated on this server, listed by username and displaying the time of creation as well as expiration (where applicable), last usage, and a description if one was included. Note that session keys are not listed here.
To revoke an API Key, such as in a case where it has been compromised or shared, select the row and click (Delete). To revoke all API Keys, select all rows and delete.
| previousnext |
| expand allcollapse all |
