How do I create a .netrc or _netrc file?

Create a file named ".netrc" ("_netrc" on Windows) in your home directory.
This file must include the following 3 lines:

machine <remote-instance-of-labkey-server>
login <user-email>
password <user-password>

E.g.:

machine labkey.scicore.unibas.ch
login eva.pujadas@unibas.ch
password xxxxx

The row "machine" denotes either the IP-address or the name of the server running the Labkey instance (the example could contain the IP-address of the "labkey.scicore.unibas.ch" server instead).
Note that you must not include "https://" or the port number (e.g. "127.0.0.1:8080") here.
The row "login" describes a valid user name for the Labkey instance. Rlabkey can access every content that the particular user has been granted permission for.
The row "password" contains the valid password of the above user for the Labkey instance.

More details in LabKey documentation Create a .netrc or _netrc file.

How do I secure the credentials file?

Two proposals:

(1) Set file permissions

(2) Encrypt

For more security, encrypt the file using PGP, for example.

Encrypt with:
$ gpg -c .netrc
Be sure to delete the original file after creating the encrypted version. Otherwise, there is no protection.
Be sure to remember keys or passphrases. There is no recovery.

And decrypt with:
$ gpg .netrc.gpg
There is no need to give the passphrase when decrypting in the same environment where the file was encrypted.

How is the credentials file accessed?

LabKey APIs will automatically access the credentials stored in the credential file, given the file is located in the right place, that is, in your home directory.

Can you give more details on Windows?

How should I create the _netrc file?

Use a text editor (e.g. TextWrangler) to create the "_netrc" file and save it as "_netrc" (without file extension such as ".txt" or the like).

Where should I store the _netrc file?

The "_netrc" file should be located in the home-directory of the computer that accesses Labkey via the APIs.
This requires you to create an environment variable containing the path to your home-directory. For more details on environment variables see this page.

What is an API key?

An API key is a long, randomly generated token that provides an alternative authentication credential for use with APIs.
API keys have security benefits over passwords:

• they are used to authenticate to a sever, avoiding the use and storage of a LabKey password on the client machine.
• they are tied to a specific server.
• they can be configured to expire.
• they can be revoked.

But since a valid API key provides complete access to your data and actions, it should be kept secret.

The API key can be used in several ways:

• specifying the key in the ".netrc" (or "_netrc") file. E.g.:
  
  machine labkey.scicore.unibas.ch
login apikey
password apikey|the_rest_of_the_long_api_key_copied
  
  
• providing it to API functions.
• using it with external clients that support Basic authentication.

More details can be found in the LabKey documentation API Keys.

How can I create an API key?

• Select the menu " --> API Keys" on the top right-hand side of the page.
• Click the button "Generate API Key".
• To grab the key, click the button "Copy to Clipboard". The button will read "Copied!" when the copy has completed.
• Finalize by clicking the button "Done".

How to disable validation of self-signed SSL certificates?

If you are using a self-signed certificate, and connecting via HTTPS on a Mac or Linux machine, you may see issues as labkey attempts unsuccessfully to validate that certificate.
Validation can be disabled in the following way:

In Rlabkey

To bypass the peer and host verification steps, add the following to your script:

> labkey.setCurlOptions(ssl_verifyhost=FALSE,ssl_verifypeer=FALSE)

More information in LabKey documentation Troubleshooting Rlabkey Connections.

In Python

To bypass the SSL verification step, add the parameter "use_ssl" with value "False" when creating the server context. E.g.:

server_context = create_server_context('labkey.scicore.unibas.ch', 'Public datasets/Iris dataset', 'labkey', use_ssl = False)