Public keys

Suggest Edits

Public keys offer a secure way to authenticate with Encord without requiring a user login and password. In particular, this is required when using the Encord SDK or Encord API. Once you have registered your public key, you can use the SDK or API to create, manage and interrogate projects, datasets and labels programmatically.

Read more about public-key cryptography here.

Generating keys in Encord (Recommended)

Navigate to the 'Public keys' section of the Settings to create, register and manage your public keys.

  1. Click the New Key button to add or generate a new key.

  2. Enter a title for your public key in the first field. Click Generate key pair to generate a new public/private key pair. The public key field will be automatically populated, while a .txt containing your corresponding private key will be downloaded. The Create button will become available once both fields have been populated.

  3. Click Create to add your public key to Encord. It will now be listed showing the key's name, as well as a signature that serves as a unique identifier.

ℹ️

Note

While key names don't have to be unique, the keys themselves do. Attempting to upload a duplicate key will result in an error.

Creating keys via Terminal / Powershell

ℹ️

Note

We strongly recommend using the Encord app to generate public-private key pairs.

Follow the steps below to generate a public-private key pair using an encryption library. Encryption libraries are part of most major operating systems, so you can generate this key pair using the appropriate terminal for your OS:

  • Linux/macOS: the default terminal
  • Windows 10 & Server 2019/2022: Powershell

To generate a public-private key pair:

  1. Open Terminal or Powershell.

  2. Run the following command:

    $ ssh-keygen -t ed25519

  3. Press enter to accept the default file location or modify as required:

    > Enter a file in which to save the key (/Users/YOU/.ssh/id_ALGORITHM): [Modify / Press ENTER]

    > Enter a file in which to save the key (C:\Users\YOU/.ssh/id_ALGORITHM): [Modify / Press ENTER]

    > Enter a file in which to save the key (/home/YOU/.ssh/id_ALGORITHM): [Modify / Press ENTER]

  4. [IMPORTANT] Leave the passphrase blank:

    > Enter passphrase (empty for no passphrase): [Press ENTER]
> Enter same passphrase again: [Press ENTER]

🚧

Caution

Please ensure that the private key you have generated is not protected by a passphrase. Password-protected private keys cannot be authenticated in Encord. All private keys generated on the Encord platform are not password-protected by default.

Now you should have two files:

  • /path/to/your/key/id_ALGORITHM contains your private key (which you should keep secure);
  • /path/to/your/key/id_ALGORITHM.pub contains your public key (usually in a file ending in .pub).

The next step is to add your public key to Encord. To add your public key to Encord:

  1. Copy the contents of the public key file. For that, execute:

    $ cat /path/to/your/key/id_ALGORITHM.pub
  # Then select and copy the contents of the id_ALGORITHM.pub file
  # displayed in the terminal to your clipboard

  2. Navigate to the 'Public keys' section of the Settings to create, register and manage your public keys.

  3. Enter a title for your public key in the first field, and paste your public key in the second field. The Create button will become available once both fields have been populated.

  4. Click Create to add your public key to Encord. It will now be listed showing the key's name, as well as a signature that serves as a unique identifier.

Authenticate with your private key

Once your public key has been registered with Encord, use your private key as your credentials when using the SDK and API. Please check the SDK or API documentation on how to authenticate with each respectively.

Updated 5 months ago