Authentication#

Types of authentication#

You can authenticate with Encord on a user basis by registering an SSH public key (i.e. “public key” in this document), or on a specific project or dataset basis by using an Encord-generated API key tied to that resource.

Resource authentication via API key (supports legacy flows)#

You can access a specific project or dataset via API key authentication. An individual API key is always tied to one specific project or dataset. This is an authentication flow that will be deprecated in the future in favour of public key authentication.

We only recommend you to use this authentication if

  • You do not have user access rights for a project or dataset

  • You want to access a project or dataset as part of an automated pipeline without using a specific user account

Note

To setup resource authentication, follow these instructions in the Resource authentication section below.

User authentication#

Set up authentication keys - user authentication#

Public keys are tied to the user so need to be added to your profile. To register a public key, please follow the instructions in Public keys of the web-app documentation.

Authenticate with Encord - user authentication#

After registering your public key, authenticate with Encord by passing the corresponding private key to an EncordUserClient. Once you have an EncordUserClient, you can use it to create new projects and datasets, or interact with existing ones by creating separate Project or Dataset objects tied to them

from pathlib import Path

from encord import Dataset, EncordUserClient, Project

# adapt the following line to your private key path
private_key_path = Path.home() / ".ssh" / "id_ed25519"

with private_key_path.open() as f:
    private_key = f.read()

user_client = EncordUserClient.create_with_ssh_private_key(private_key)
project: Project = user_client.get_project("<project_id>")
dataset: Dataset = user_client.get_dataset("<dataset_id>")

Resource authentication#

This is an authentication flow that will be deprecated in the future in favour of public key authentication.

Set up authentication keys - resource authentication#

API keys are tied to specific projects or datasets. You can generate multiple keys for each project or dataset.

To create an API key use the web-app:

  1. Log in to your account on Login URL

  2. Navigate to the Project or Dataset tab in the Navigation bar

  3. Select a project or dataset

  4. Navigate to the ‘Settings’ tab and select the ‘API access’ pane on the left

  5. Click on the + New API key button, select relevant scopes and click the Create button

  6. Copy your API key and make a note of the project or dataset ID. The API key is only displayed once. Example code is also displayed

_images/api-key.png

Getting an API key from the web-app.#

You can additionally create them programmatically as you can see in these guides:

Authenticate with Encord - resource authentication#

If you are using API key authentication, authenticate with Encord by passing the resource ID (project or dataset ID) and associated API key to an EncordClient. This will directly create an EncordClient to interact with a specific project or dataset.

from typing import Union

from encord.client import EncordClient, EncordClientDataset, EncordClientProject

# The client will either be an EncordClientDataset if the
# resource_id belongs to a dataset or it will be an
# EncordClientProject if the resource_id belongs to a project.
client: Union[
    EncordClientProject, EncordClientDataset
] = EncordClient.initialise("<resource_id>", "<resource_api_key>")

Note

The encord.client.EncordClientProject is functionally equivalent to the Project, and the recomended interface going forward. The encord.client.EncordClientDataset is functionally equivalent to the Dataset, and the recomended interface going forward.