API keys provide a secure way to authenticate with Encord without needing a user login or password. They are used for authentication when working with the Encord SDK or API. After registering your public key, you can programmatically create, manage, and query Projects, Datasets, and labels through the SDK or API.

Encord uses public/private key pairs for API keys. You register a public key with Encord and securely store the private key. The private key is then used for authentication. Learn more about public-key cryptography here.

  1. 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.

  1. Give the public key a meaningful name.

  2. Click Generate key pair to generate a new public/private key pair. The public key field is automatically populated, and a .txt containing your corresponding private key is downloaded.

You must click Create to create your API key. The Create button becomes available once both fields are populated.

  1. Click Create to add your public key to Encord. The key is now listed in the Public keys section along with an ID that serves as a unique identifier.

Key names do not have to be unique, but the keys themselves do. Attempting to upload a duplicate key results in an error.

​
Creating keys using Terminal / Powershell

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, therefore 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:

    Mac
    > Enter a file in which to save the key (/Users/YOU/.ssh/id_ALGORITHM): [Modify / Press ENTER]
    Windows
    > Enter a file in which to save the key (C:\Users\YOU/.ssh/id_ALGORITHM): [Modify / Press ENTER]
    Linux
    > 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]

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.

You should now 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.

  1. 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.

  2. 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

After registering your public key with Encord, use your private key as credentials to authenticate the SDK or API. For detailed instructions, refer to the SDK or API documentation.

Was this page helpful?

SettingsActivity Log