directus/docs/guides/api-config.md

Configuring the API

toc

Cache

Directus has a built-in way to do data-caching. Enabling this will cache the output of the request (based on the current user and exact query parameters used) into to configured cache storage location. This will drastically improve API performance, as subsequent requests are served straight from this cache. Enabling cache will also make Directus return accurate cache-control headers. Depending on your setup, this will further improve performance by caching the request in middleman servers (like CDNs) and even the browser.

You can enable the data-cache with the CACHE_ENABLED environment variable.

Cache Store

In bigger projects, you most likely don't want to rely on local memory to keep the caches. Instead, you can use the CACHE_STORE environment variable to tell Directus to use either memcache or redis to store the caches.

CACHE_ENABLED="true"

CACHE_STORE="redis"
CACHE_REDIS="redis://@127.0.0.1"

Auto-Purging

Directus can automatically clear the caches whenever a create/update/delete action is performed. This allows you to keep the Directus API real-time, while still getting the performance benefits on quick subsequent reads.

CACHE_AUTO_PURGE="true"

TTL

Based on your project's needs, you might be able to aggressively cache your data, only requiring new data to be fetched every hour or so. This allows you to squeeze the most performance out of your Directus instance. This can be incredibly useful for applications where you have a lot of (public) read-access and where updates aren't real-time (for example a website). CACHE_TTL uses ms to parse the value, so you configure it using human readable values (like 2 days, 7 hrs, 5m).

CACHE_TTL="1h"

Assets

The cache-control header for the /assets endpoint is separate from the regular data-cache. This is useful as it's often possible to cache assets for way longer than you would with the actual content.

ASSETS_CACHE_TTL="7d"

oAuth (Single Sign-On (SSO) / OpenID)

Directus' oAuth integration provides a powerful alternative way to authenticate into your project. Directus will ask you to login on the external service, and if your user exists in Directus, you'll be logged in automatically.

Directus relies on grant for the handling of the oAuth flow. This means that there's hundreds of services that are supported out of the box. For example, enabling logging in through GitHub is as easy as creating an oAuth app in GitHub and adding the following to Directus:

OAUTH_PROVIDERS="github"
OAUTH_GITHUB_KEY="99d3...c3c4"
OAUTH_GITHUB_SECRET="34ae...f963"

::: warning PUBLIC_URL

The oAuth flow relies on the PUBLIC_URL variable for it's redirecting. Make sure that variable is configured correctly.

:::

Multiple Providers

OAUTH_PROVIDERS accepts a CSV of providers, allowing you to specify multiple at the same time:

OAUTH_PROVIDERS ="google,microsoft"

OAUTH_GOOGLE_KEY = "<google_application_id>"
OAUTH_GOOGLE_SECRET=  "<google_application_secret_key>"
OAUTH_GOOGLE_SCOPE="openid email"

OAUTH_MICROSOFT_KEY = "<microsoft_application_id>"
OAUTH_MICROSOFT_SECRET = "<microsoft_application_secret_key>"
OAUTH_MICROSOFT_SCOPE = "openid email"
OAUTH_MICROSOFT_AUTHORIZE_URL = "https://login.microsoftonline.com/<microsoft_application_id>/oauth2/v2.0/authorize"
OAUTH_MICROSOFT_ACCESS_URL = "https://login.microsoftonline.com/<microsoft_application_id>/oauth2/v2.0/token"

PUBLIC_URL = "<public_url_of_directus_instance>"

Provider Specific Configuration

If you use one of the many supported providers, you often don't have to configure any more than just the key and secret for the service. That being said, if you use a more tailored service (like the specific Microsoft application in the example above), you might have to provide more configuration values yourself. Please see https://github.com/simov/grant#configuration-description for a list of all available configuration flags.

File Storage

By default, Directus stores every file you upload locally on disk. Instead of local file storage, you can configure Directus to use S3 or Google Cloud Storage instead:

STORAGE_LOCATIONS="aws"

STORAGE_AWS_DRIVER="s3"
STORAGE_AWS_KEY="tp15c...510vk"
STORAGE_AWS_SECRET="yk29b...b932n"
STORAGE_AWS_REGION="us-east-2"
STORAGE_AWS_BUCKET="my-files"

Multiple Storage Adapters

You can configure multiple storage adapters at the same time. This allows you to choose where files are being uploaded on a file-by-file basis. To do this, you can provide a CSV of storage location names, and provide a config block for each of them:

STORAGE_LOCATIONS="local,aws"

STORAGE_LOCAL_DRIVER="local"
STORAGE_LOCAL_ROOT="local"

STORAGE_AWS_KEY="tp15c...510vk"
STORAGE_AWS_SECRET="yk29b...b932n"
STORAGE_AWS_REGION="us-east-2"
STORAGE_AWS_BUCKET="my-files"

In the Admin App, files will automatically be uploaded to the first configured storage location (in this case local). The used storage location is saved under storage in directus_files.

Rate Limiting

You can use the built-in rate-limiter to prevent users from hitting the API too much. To enable the rate-limiter, simply set

RATE_LIMITER_ENABLED="true"

This will kick-in the rate-limiter on a maximum of 50 requests a second. You can configure this using:

// 10 requests per 5 seconds

RATE_LIMITER_POINTS="10"
RATE_LIMITER_DURATION="5"

Once you have multiple copies of Directus running under a load-balancer, or your user base grows so much that memory is no longer a viable place to store the rate limiter information, you can use an external memcache or redis instance to store the rate limiter data:

RATE_LIMITER_ENABLED="true"

RATE_LIMITER_POINTS="10"
RATE_LIMITER_DURATION="5"

RATE_LIMITER_STORE="redis"

RATE_LIMITER_REDIS="redis://@127.0.0.1"

File-Based Configuration

In case you prefer using a configuration file instead of environment variables, you can use the CONFIG_PATH environment variable to instruct Directus to use a local configuration file instead of environment variables. See Config Files for more information.