Appwrite now features dynamic keys, significantly improving how you manage API keys within your projects. These keys (also known as ephemeral keys) are designed to enhance security and facilitate easier local development and environment setup. As part of the Appwrite Functions ecosystem, they reduce the need for manual key management and rotation, making your applications (and functions!) easier to maintain.
This guide will walk you through understanding, setting up, and effectively using dynamic API keys in your projects.
New additions and syntax in Appwrite
With Appwrite 1.6 comes two important variables:
APPWRITE_FUNCTION_API_ENDPOINT:
Appwrite now automatically provides the API endpoint as an environment variable during function execution, ensuring your function always uses the correct API endpoint. This eliminates the need to manually set the endpoint in your function code or environment variables.
Along with the existing APPWRITE_FUNCTION_PROJECT_ID variable, this setup eliminates the need to manually set the endpoint and project ID in your function code or environment variables, making the integration seamless.
req.headers['x-appwrite-key']
This variable contains the dynamic API key generated for each function execution. With this key, you no longer need to manually generate or manage API keys for your functions. Additionally, you can set the scopes for this key in the Appwrite Console under function settings.
These additions simplify the process of setting up and maintaining secure API access for your functions. In the following sections, we'll discuss dynamic API keys in more detail, with examples of how to use them in your projects.
What are dynamic keys?
Dynamic API keys are short-lived API keys that Appwrite automatically generates for each function execution. These keys are unique to each function run and have specific scopes which enhances security by reducing their lifespan and exposure. In contrast, long-lived keys pose a higher risk if compromised.
How dynamic keys differ from standard keys
Ephemeral keys and standard keys differ in several fundamental ways. Standard API keys are manually created and long-lived, meaning they require regular rotation and diligent management to ensure security. In contrast, dynamic API keys are automatically generated per execution and are short-lived, expiring after the function completes. This automatic generation means there is no need to embed these keys in environment variables manually, reducing setup complexity and maintenance.
While we generally recommend using ephemeral keys, some third-party services may require long-lived keys, or may not support Appwrite's dynamic key generation. In such cases, you can still use standard API keys, but use caution and ensure proper key management practices.
Benefits of ephemeral keys
Dynamic API keys offer several advantages:
Enhanced security: The short-lived nature of dynamic API keys minimizes the risk of key exposure and misuse. Each key is unique to a specific function execution, reducing the attack surface.
Simplified management: Since these keys are automatically generated and do not require manual rotation or embedding in environment variables, the administrative overhead is significantly reduced.
Granular control: Each ephemeral key can be assigned specific scopes tailored to the function's overall needs. This ensures that functions only have the permissions they require, adhering to the principle of least privilege.
Consistency in development and production: In Appwrite, dynamic keys respect the scopes set in appwrite.json, ensuring that the behavior is consistent across both local development and production environments.
Setting up and using dynamic API keys
Step-by-step guide
1. Initial setup: To begin, create and configure your function in the Appwrite console or locally using the Appwrite CLI.
2. Configuring scopes: Scopes control the permissions of the dynamic API key. You can define the necessary scopes for your function in the Appwrite console. This ensures that the function only has access to the required resources.
To define scopes in the Appwrite console, navigate to your function's settings and scroll down to the "Scopes" section. Here, you can select the required scopes for your function.
3. Writing the function code: In the old approach, the API endpoint and API key were typically hardcoded within the function. You would manually specify the endpoint URL and use a static API key stored in environment variables like this:
const client = new Client()
.setEndpoint('https://cloud.appwrite.io/v1') // Hardcoded API endpoint
.setProject(process.env.APPWRITE_FUNCTION_PROJECT_ID)
.setKey(process.env.APPWRITE_API_KEY) // Static API key
While this approach still works, you can now leverage dynamic keys for better security and ease of use. To do this, update your function code to use the new environment variable for the API endpoint and obtain the dynamic API key from the request headers. Here's how you can modify your function code to use dynamic API keys:
const client = new Client()
.setEndpoint(process.env.APPWRITE_FUNCTION_API_ENDPOINT)
.setProject(process.env.APPWRITE_FUNCTION_PROJECT_ID)
.setKey(req.headers['x-appwrite-key'])
In the above example, the environment variable APPWRITE_FUNCTION_API_ENDPOINT is used for the endpoint, and the API key is obtained from req.headers['x-appwrite-key'].
4. Deploying and testing the function: Deploy your function through the Appwrite console or the Appwrite CLI. Test the function by calling its endpoint and verifying that it performs the intended operations, such as creating a new document in the database.
Using dynamic API keys in local functions
Dynamic API keys also work when running functions locally and respect the scopes set in appwrite.json. Here's our guide on running functions locally.
If you’ve made changes to your project in the Appwrite console, you can easily synchronize your local functions by running appwrite pull functions on your command line. This ensures that the same scopes are applied when running the function locally. If you want to deploy your function afterwards, you can run the command appwrite push functions.
Conclusion
Dynamic API keys in Appwrite provide a more secure, manageable, and efficient way to handle API access in your functions. By leveraging automatic key generation and specific scopes, you can ensure your applications are both secure and easy to manage. If you haven't already, upgrade your Appwrite CLI and SDKs to the latest version to take advantage of our new features.
Further reading and resources:
