Evervault provides a secure and easy-to-use authentication mechanism for APIs using API keys. These keys authenticate API requests by passing them in HTTP headers or as a parameter to the Evervault SDKs.

API keys can be created and managed on a per-app basis in the Evervault Dashboard, and can be scoped to control access to specific resources and services, ensuring that your API keys only have access to the resources they need.

Here are some examples of what API keys can be used for:

Create an API key to run a specific function
Create an API key to decrypt data sent to a specific domain using Outbound Relay
Create an API key to deploy functions
…

Create an API Key

API keys are an important security mechanism for authenticating API requests. Evervault makes it easy to create and manage them.

Create an API Key

To create an API key, follow these steps:

Sign in to the Evervault dashboard.
Select the app you want to create an API key for.
Go to the app settings.
Go to the "Scoped API Keys" section.
Click "Create Key".
Select the actions and resources the API key can access.
Click "Save".
Store the API key securely in your application.

The plaintext value of an API key can only be fetched once when it is created, so it's essential to store and manage them securely to ensure the integrity of your Evervault account.

Manage existing API Keys

API keys can be updated and revoked in the Evervault dashboard. This allows you to ensure that your API keys are secure and that they only have access to the resources they need. To edit an API key, follow these steps:

Sign in to the Evervault dashboard.
Select the app containing the API key you want to update.
Go to the app settings (App Settings tab).
Go to the "Scoped API Keys" section.
Click on the 3 dots (…) button next to the API key you want to revoke. Then click “Edit Key”.
Update the actions and resources the API key can access.
Click "Save".

Edit an API Key

Rotate an API Key

To maintain the security of your Evervault account, it's important to regularly rotate your API keys. To rotate a key, you can create a new scoped key with the same permissions as the old key. Once the new key is in use, you can remove the old key from your account. This ensures that any potential security vulnerabilities associated with the old key are eliminated, while still allowing your application to function properly with a new key.

Revoke an API Key

To revoke an API key, follow these steps:

Sign in to the Evervault dashboard.
Select the app containing the API key you want to revoke.
Go to the app settings (App Settings tab).
Go to the "Scoped API Keys" section.
Click on the 3 dots (…) button next to the API key you want to revoke. Then click “Delete Key”.
Confirm that you want to revoke the API key.

API Key permissions

API key permissions determine what actions and resources an API key can access. This ensures that API keys only have access to the resources they need, improving the security of your Evervault account.

The following table contains all the available API key permissions:

Action	Description	Resources
Encrypt	Encrypt data — All API keys can be used to encrypt data. This permission is available by default and can’t be removed.
Functions Deploy	Deploy a function using the CLI. If a function is deployed for the first time using the CLI, the permission is also required.	All or any Functions
Functions Create	Create a function using the Evervault CLI
Functions Run	Run a function	All or any Functions
Functions Create Run Token	Create a function run token	All or any Functions
Functions Create	Create a function using the Evervault CLI
Functions Update	Update a function (e.g. environment variables, etc.) using the Evervault CLI	All or any Functions
Functions Delete	Delete a function using the Evervault CLI	All or any Functions
Functions List	List all functions using the CLI
Functions Read	Get information about a function using the CLI	All or any Functions
Cages Create	Initialize a cage using the Evervault Cage CLI
Cages Deploy	Deploy a new version of a cage using the Evervault Cage CLI	All or any Cages
Cages Invoke	Send an authenticated request to a cage using the `api-key` header.	All or any Cages
Cages Create Secret	Add an Environment Variable to a cage using the Evervault Cage CLI	All or any Cages
Cages Delete Secret	Delete an Environment Variable from a cage using the Evervault Cage CLI	All or any Cages
Cages Delete	Delete a cage using the Evervault Cage CLI	All or any Cages
Cages List	List Cages for an app using the Evervault Cage CLI
Cages Read	Used for any read operations using the Evervault Cage CLI	All or any Cages
Outbound Relay Proxy	Share encrypted data with third-party APIs using Outbound Relay.	All or any Outbound Destinations
Inbound Relay mTLS Proxy	Authenticate mTLS requests with Inbound Relay, This permission is not required when using non-mTLS Inbound Relays.	All or any Inbound Relays

Keep your API Keys safe

API keys should be kept safe to prevent unauthorized access to sensitive resources and services, and to maintain the security and integrity of your Evervault account.

Here are some tips on how to keep your API keys safe:

Do not share your API keys: API keys are sensitive and should not be shared with anyone. Keep them secure and only provide access to those who need it.
Store API keys securely: Store your API keys in a secure location, such as a password manager, and never store them in plain text or in public repositories.
Rotate API keys regularly: Regularly rotate your API keys, especially if they have been compromised or if access is no longer required.
Restrict API key access: Limit access to your API keys by scoping them to specific resources and services. This ensures that they only have access to the resources they need.
Do not embed API keys directly in code: Embedding API keys directly in code, such as in configuration files, can make them more vulnerable to exposure. Instead, use environment variables or a configuration file that is not included in version control to store and manage your API keys.

Global API Keys

Global API keys are deprecated in favour of scoped API keys.

Global API keys are API keys that have all permissions set by default. Existing global API keys will be migrated into scoped API keys that have all permissions. This will have no impact on current implementations. Scoped API keys provide a more secure and flexible way to control access to Evervault services.