API Keys

🚧

Caution

API keys are deprecated and are not maintained. We strongly advise using SSH keys for authentication. Please see our documentation on authentication for more information.

Resource authentication using an API key allows you to authenticate specific Datasets and Projects. This can be useful if you, for example, want to share read-only access with some third-party.

Creating API keys

Creating a Project API key

ℹ️

Note

Only project admins can create Project API keys

You can create a project API key using the create_project_api_key() method, which is required to interact with a project using encord.project.Project.

The create_project_api_key() method takes three arguments:

  • project_id: The <project_hash> of your project, obtained - for example - by Creating a Project or Listing existing projects.

  • api_key_title: The title of the API key.

  • scopes: A list of APIKeyScopes enum values specifying what is accessible with the API key.

The following code example creates an API key with read and write permissions for the project labels. For the full set of permissions, see APIKeyScopes.


from encord.user_client import EncordUserClient
from encord.utilities.client_utilities import APIKeyScopes

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )


api_key: str = user_client.create_project_api_key(
    "<project_hash>",
    "Example API key title",
    [
        APIKeyScopes.LABEL_READ,
        APIKeyScopes.LABEL_WRITE,
    ],
)
print(api_key)



# the <project_api_key>
"0-1aABCDE_aFGcdeHIfJ2KfLMgNO3PQh4RST5UV6W_X"

You use the <project_id> and <project_api_key> to obtain a Resource authentication which is specific to the project with the specified permissions.

Creating a Dataset API key

Use the example below to create a Dataset API key.


from encord import EncordUserClient
from encord.orm.dataset import DatasetAPIKey, DatasetScope

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )


dataset_api_key: DatasetAPIKey = user_client.create_dataset_api_key(
    "<dataset_hash>",
    "Full Access API Key",
    [DatasetScope.READ, DatasetScope.WRITE],
)
print(dataset_api_key)



DatasetAPIKey(
  dataset_hash="<dataset_hash>",
  api_key="<api_key>",
  title="Example api key title",
  scopes=[
      DatasetScope.READ,
      DatasetScope.WRITE,
  ]
)

Creating a master API key with full rights

It is also possible to create or get a master API key with full access to all APIKeyScopes. The following example show how to obtain a master API key:


from encord.user_client import EncordUserClient

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

api_key = user_client.get_or_create_project_api_key(
    "<project_hash>",
)
print(api_key)




# the <project_api_key>
"0-1aABCDE_aFGcdeHIfJ2KfLMgNO3PQh4RST5UV6W_X"

Fetching API keys

Fetching Dataset API keys

If you haven’t created a dataset already, you can have a look at our documentation on how creating a Dataset.


from typing import List
from encord import EncordUserClient
from encord.orm.dataset import DatasetAPIKey

user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )


keys: List[DatasetAPIKey] = user_client.get_dataset_api_keys("<dataset_hash>")
print(keys)

Fetching Project API keys

All API keys for an existing project can be obtained using the <project_hash> which uniquely identifies a project. Before you can fetch API keys, you need to:

  1. Create a Project.
  2. Add at least one API key to the Project.

from typing import List
from encord.orm.project_api_key import ProjectAPIKey
from encord.user_client import EncordUserClient

user_client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path=
"<private_key_path>"
)

api_keys: List[ProjectAPIKey] = user_client.get_project_api_keys(
    "<project_hash>"
)
print(api_keys)



[
    ProjectAPIKey(
        api_key="0-1aABCDE_aFGcdeHIfJ2KfLMgNO3PQh4RST5UV6W_X",
        title="Example title",
        scopes=[
            APIKeyScopes.LABEL_READ,
            APIKeyScopes.LABEL_WRITE,
        ]
    ),
    # ...
]