API Keys can be used to authenticate client code accessing LabKey Server using one of the LabKey Client APIs. Authentication with an API key avoids needing to store your LabKey password or other credential information on the client machine. When desired, a single user can have multiple simultaneous API keys that allow the same access for different purposes
An API key can be specified in .netrc, provided to API functions, and used with external clients that support Basic authentication. API keys have security benefits over passwords (they are tied to a specific server, they're usually configured to expire, they can be revoked, and they provide API access for users who sign in via single sign-on authentication mechanisms such as CAS and SAML), but a valid API key provides complete access to your data and actions, so it should be kept secret.
An administrator can configure the server to allow users to obtain an
API Key (or token) once they have logged in. API keys can be configured to expire after a duration specified by the administrator. An administrator also retains the power to immediately deactivate one or more API keys whenever necessary.
In cases where access must be tied to the current browser session and run under the current context (e.g., your user, your authorizations and if applicable, your declared terms of use and PHI level, your current impersonation state, etc.), such as some compliance environments, you will need to use a
session key. Session keys expire at the end of the session, whether by timeout or explicit logout.
Configure API Keys (Admin)
- Select (Admin) > Site > Admin Console.
- Under Configuration, click Site Settings.
- Under Configure API Keys, check the box for Let users create API keys.
- Select when to Expire API keys. Options:
- Never (default)
- 7 days
- 30 days
- 90 days
- 365 days
Access and Use an API Key (Developers/Users)
Once enabled, a logged-in user can retrieve an API key via
username > External Tool Access:
Click
Generate API Key to create a key.
The API key is a long, randomly generated token that provides an alternative authentication credential for use with APIs.
Click
Copy to Clipboard to grab it. The button will read
Copied! when the copy has completed. Then click
Done.
You can then use this key in a .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.
Note: When an administrator is impersonating a user, group or role, they cannot generate an API key.
Example: .netrc File
To avoid embedding credentials into your code, you can use the API key as a password within a
.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.
Manage API Keys (Admin)
A site administrator can manage API keys generated on the server using the APIKey query. Link to it from the top of the
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). Note that
session keys are not listed here, and there is no ability for a non-admin user to see or delete their own keys.
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.
Related Topics
