# API Keys Cloud

API keys are how clients authenticate with the Prefect Cloud API. They encapsulate the identity of a User or a service account. Ultimately, all clients that interact with the Prefect Cloud API must provide an API key as a Bearer Token included in the request header.

See our API documentation more information on how to use these keys to interact with the GraphQL API.

# User API Keys

Users can generate API keys to interact with the API with their personal permissions. When creating an API key, you can configure the following attributes:

  • API Key Name: A memorable name for the key
  • API Key Expiration: An optional expiration date for the key. If no expiration is provided, the key will never expire
  • Default Tenant: The tenant to associate with the API key. Clients using this key will default to performing actions in this tenant, but they can also provide another tenant to perform actions in.

To generate an API key for your User, navigate to Account Settings > API Keys within the UI and click "Create an API Key".

Security best practice

When you need to create a long-lived key for CI, a Prefect Agent, or any use beyond local development, create an API key for a service account instead of for your user. Actions performed in an automated setting should not be linked to your user identity and should not require the permissions of a full user.

# Service Account API Keys

Users can generate API keys for service accounts, which have permissions restricted to the tenant the service account belongs to. These keys will not inherit the full permissions of the user creating them. To create and manage your tenant's service accounts and their associated API keys, navigate to Team > Service Accounts.

When creating an API key, you can configure the following attributes:

  • API Key Name: The name of this key; this is useful for organizational and bookkeeping purposes
  • API Key Expiration: An optional expiration date for the key - if no expiration is provided, the key will never expire

Service account creation

Note that service accounts can only be created by tenant admins.

GraphQL API

To create an API key using GraphQL use the create_api_key mutation. For more information on how to use the GraphQL API go here. For a user_id, supply either your user id or a service account id.

mutation {
  create_api_key(input: { user_id: <user_id>, name: "my-api-key" }) {
    key
  }
}

# Using API keys

To authenticate with an API key, we recommend using the CLI.

$ prefect auth login --key <YOUR-KEY>

This will store your key on disk and load it each time you use Prefect locally. Once you've logged in, you can easily view the tenants you belong to and switch between tenants.

You may also provide your key with an environment variable or the config. This is often preferable for CI jobs. If you want to use a tenant other than the default tenant associated with the key, you'll need to set that as well.

export PREFECT__CLOUD__API_KEY="<YOUR-KEY>"
# Optional
export PREFECT__CLOUD__TENANT_ID="<TENANT-ID>"

Modify ~/.prefect/config.toml

[cloud]
api_key = "<YOUR-KEY>"

# Optional
tenant_id = "<TENANT-ID>"

Specifying a key for agents

Agents will load keys from these default locations as described above, but you can also pass an override directly to the agent when you start it. For example:

prefect agent local start --key "<YOUR-KEY>"

# Querying for API key metadata

Your API key metadata can be viewed in serveral ways. Note that we do not store your API keys and you will not be able to view the value of the key after creation. When querying for keys, you will only be able to see metadata for keys created by your user or, if the you are a tenant admin, metadata for the all service account API keys in the tenant.

To see keys from the CLI, use the prefect auth list-keys command

$ prefect auth list-keys
NAME          ID                                    EXPIRES AT
test          9714235e-46ac-4fb8-9bb0-d615d5318fb9  NEVER
my_key        5441f413-4b9d-4630-8b1c-0103aa38736e  NEVER
their_key     01c0e2ea-8bfe-49e3-8c63-c477cf2ec024  2021-06-15T09:42:07.802718

To query for information about API keys with GraphQL, use the auth_api_key query.

query {
  auth_api_key {
    id
    name
    expires_at
    user_id
  }
}

Example response:

  "data": {
    "auth_api_key": [
      {
        "id": "9714235e-46ac-4fb8-9bb0-d615d5318fb9",
        "name": "test",
        "expires_at": null,
        "user_id": "84ac3f7e-78b3-458c-93cf-81bd920669b8"
      },
      {
        "id": "5441f413-4b9d-4630-8b1c-0103aa38736e",
        "name": "my_key",
        "expires_at": null,
        "user_id": "b5810ca3-f90b-4698-8c22-ae958aabc992"
      },
      {
        "id": "01c0e2ea-8bfe-49e3-8c63-c477cf2ec024",
        "name": "their_key",
        "expires_at": "2021-06-15T09:42:07.802718",
        "user_id": "b5810ca3-f90b-4698-8c22-ae958aabc992"
      },
    ]
  }

# Revoking Keys

To revoke an API key in the UI navigate to Team Settings > Service Accounts or Account Settings > API Keys. On your list of keys click the trash bin icon next to any key in order to revoke it. A confirmation box should appear asking if you are sure you want to revoke the key.

api key revoke

To revoke an API key from the Prefect CLI, use the prefect auth revoke-key command. You will likely need to retrieve the ID of they key with prefect auth list-keys first.

prefect auth revoke-key --id API_KEY_ID

To revoke an API key using GraphQL execute the delete_api_key mutation. For information on how to find an API key's ID, see [Querying for API key metadata]](api_keys.html#querying-for-api-key-metadata).

mutation {
  delete_api_key(input: { key_id: "API_KEY_ID" }) {
    success
  }
}

# Using API keys with older versions of Prefect

The prefect auth login command will not work with API keys and the PREFECT__CLOUD__API_KEY setting will be ignored before version 0.15.0. In older versions, there were authentication tokens. Keys can be used in-place in older versions by setting them in the config or the environment in the PREFECT__CLOUD__AUTH_TOKEN setting.

Using an API key as a token for registering flows

export PREFECT__CLOUD__AUTH_TOKEN="<YOUR-KEY>"

Using an API key as a token for starting an agent by CLI

$ prefect agent local start -k "<SERVICE_ACCOUNT_API_KEY>"

Using an API key as a token for starting an agent by environment

$ export PREFECT__CLOUD__AGENT__AUTH_TOKEN="<YOUR-KEY>"
$ prefect agent local start

# Removing API tokens

If you've used prefect auth login with an API token or have set an API token in your config or environment, you will receieve warnings starting with version 0.15.0 that tokens have been deprecated. API keys are more secure and simpler to use, we urge you to switch over.

If you logged in with prefect auth login, you can remove your token with prefect auth logout --token or rm -r ~/.prefect/client.

If you set your token in the environment, you can unset it with unset PREFECT__CLOUD__AUTH_TOKEN.

If you set your token in the config, you will have to modify ~/.prefect/config.toml to remove it.

WARNING

If you have logged in with an API key but a token still exists on your machine, the API key will be used and the token will be ignored.