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.
User authentication via public key (recommended)#
Public key authentication gives you full access to all the capabilities of the SDK. This is our recommended default authentication method.
Public key authentication is required to use the EncordUserClient.
You can use the client to interact with a Dataset or a Project assuming you are either of the following:
An organisation admin of the organisation this project or dataset is part of
A project admin or project manager of the project that is being accessed
A dataset admin of the dataset that is being accessed
Note
To setup public key authentication, follow these instructions in the User authentication section below.
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:
Log in to your account on Login URL
Navigate to the Project or Dataset tab in the Navigation bar
Select a project or dataset
Navigate to the ‘Settings’ tab and select the ‘API access’ pane on the left
Click on the + New API key button, select relevant scopes and click the Create button
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
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.