- Stitch >
- Application Deployment >
- Reference
Application Configuration Files¶
On this page
Overview¶
Stitch uses JSON files and source code files to define and configure every component of an application. Each component has a specific configuration file schema and every application uses a standard file structure to organize the configuration files.
When Will I Use Configuration Files?¶
Every Stitch app is composed of a collection of configuration files, so you use application configuration files whenever you create or modify a Stitch application. If you use the Stitch UI then you rarely deal directly with the configuration files themselves, but other deployment methods, like Stitch CLI and GitHub allow you to define and edit the configuration files directly.
Directory Structure¶
The following figure shows a high-level view of a Stitch application’s directory structure:
Application Configuration¶
stitch.json
stored in your application’s root
directory.Configuration¶
Field | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
app_id String
|
The application’s App ID. | ||||||||||||
name String
|
The application’s name. App Name Limitations Application names must be between 1 and 32 characters and may only contain ASCII letters, numbers, underscores, and hyphens. |
||||||||||||
security Document
|
A document that contains configuration options for application-level security features.
|
||||||||||||
hosting Document
|
A document that contains configuration options for all hosted files:
|
||||||||||||
config_version Number
|
The schema version that all configuration files in the application conform to. This value is machine generated and you typically should not manually set or modify it. | ||||||||||||
custom_user_data_config Document
|
A document that contains configuration options for custom user data.
|
||||||||||||
deployment_model String
|
The application’s deployment model. The following values are valid:
|
||||||||||||
location String
|
The name of the cloud region that the application is deployed in.
|
Authentication Providers¶
Authentication providers are defined
in your application’s /auth_providers
directory.
Each provider is defined in its own JSON file named after the provider. For detailed information on configuring and using a specific authentication provider, see that provider’s reference page.
Configuration¶
Field | Description |
---|---|
id String
|
A value that uniquely identifies the authentication provider. Stitch automatically generates a unique ID for a provider when you create it. |
name String
|
The name of the authentication provider. |
type String
|
The type of the authentication provider. Valid Options:
|
config Document
|
A document that contains configuration values that are specific to the authentication provider. The existence of this field and its exact configuration fields depend on the provider type. |
secret_config Document
|
A document where each field name is a private configuration field for the provider and the value of each field is the name of a Secret that stores the configuration value. |
metadata_fields Array<Document>
|
An array of documents where each document defines a metadata field that describes the user. The existence of this field and the exact format of each metadata field document depends on the provider type. |
disabled Boolean
|
If true , this authentication provider is not enabled for your
application and cannot be used. |
Functions¶
Stitch functions are defined in a sub-directory of your application’s
/functions
directory. Each function maps to its own subdirectory
with the same name as the function.
Each function is configured in config.json
and has its source
code defined in source.js
.
Configuration¶
Field | Description |
---|---|
id String
|
A value that uniquely identifies the function. Stitch automatically generates a unique ID for a function when you create it. |
name String
|
The name of the function. The name must be unique among all functions in your application. |
private Boolean
|
If true , this function may only be accessed from incoming
webhooks, rules, and named functions. |
can_evaluate Document
|
A rule expression that
evaluates to true when the function is allowed to execute in
response to a given request. |
disable_arg_logs Boolean
|
If true , Stitch omits the arguments provided to a function
from the function execution log entry. |
run_as_system Boolean
|
If true , this function runs as the system user. This overrides any values defined for
run_as_user_id and run_as_user_id_script_source . |
run_as_user_id String
|
The unique ID of a Stitch User that the
function always executes as. Cannot be used with
run_as_user_id_script_source . |
run_as_user_id_script_source String
|
A stringified function that runs whenever the
function is called and returns the unique ID of a Stitch
User that the function executes as. Cannot be used with
run_as_user_id . |
Source Code¶
External Services¶
Services, including both MongoDB services and
external services, are defined the /services
directory. Each service maps to its own sub-directory with the same
name as the service.
Each service directory contains a service configuration file
(config.json
), a sub-directory of service rule configurations
(/rules
), and a sub-directory of webhook configurations
(/incoming_webhooks
) if the service supports webhooks.
Service Configuration¶
Field | Description |
---|---|
id String
|
A string that uniquely identifies the service. Stitch automatically generates a unique ID for a service when you create it. |
name String
|
The name of the service. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens. |
type String
|
The type of the service. Valid Options:
|
config Document
|
A document with fields that map to additional configuration
options for the service. The exact configuration fields depend on
the service |
secret_config Document
|
A document where each field name is a private configuration field for the service and the value of each field is the name of a Secret that stores the configuration value. |
External Service Rules¶
Rules for a specific external service are defined in the /<service
name>/rules
sub-directory.
Each rule maps to its own JSON file with the same name as the rule.
Field | Description |
---|---|
id String
|
A string that uniquely identifies the rule. Stitch automatically generates a unique ID for a rule when you create it. |
name String
|
The name of the service rule. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens. |
actions Array<String>
|
A list of service actions that the rule applies to. The specific
actions available depend on the service type . |
when Document
|
A rule expression that
evaluates to true when the rule applies to a given request. |
MongoDB Collection Rules¶
MongoDB collection rules have a different schema than other service rules. Each collection’s rules are stored in a JSON file with the same name as the collection namespace.
Field | Description | ||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id String
|
A string that uniquely identifies the trigger. Stitch automatically generates a unique ID for a trigger when you create it. | ||||||||||||||||||||||||||||
database String
|
The name of the database that holds the collection. | ||||||||||||||||||||||||||||
collection String
|
The name of the collection. | ||||||||||||||||||||||||||||
roles Array<Document>
|
An array of Query Role configuration documents, which have the following form:
|
||||||||||||||||||||||||||||
schema Document
|
A Document Schema. The root level schema must be an object schema, which has the following form: |
||||||||||||||||||||||||||||
filters Array<Document>
|
An array of Query Filter configuration documents, which have the following form:
|
Incoming Webhooks¶
Incoming webhooks for a specific service are defined in the
/<service name>/incoming_webhooks/
sub-directory.
Incoming webhooks use the same configuration format as function but have additional configuration parameters.
Configuration¶
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
id String
|
A value that uniquely identifies the function. Stitch automatically generates a unique ID for a function when you create it. | ||||||||
name String
|
The name of the function. The name must be unique among all functions in your application. | ||||||||
private Boolean
|
If true , this function may only be accessed from incoming
webhooks, rules, and named functions. |
||||||||
can_evaluate Document
|
A rule expression that
evaluates to true when the function is allowed to execute in
response to a given request. |
||||||||
disable_arg_logs Boolean
|
If true , Stitch omits the arguments provided to a function
from the function execution log entry. |
||||||||
run_as_system Boolean
|
If true , the webhook function runs as the system user. This overrides any values defined for
run_as_user_id and run_as_user_id_script_source . |
||||||||
run_as_user_id String
|
The unique ID of a Stitch User that the
function always executes as. Cannot be used with
run_as_user_id_script_source . |
||||||||
run_as_user_id_script_source String
|
A stringified function that runs whenever the
webhook is called and returns the unique ID of a Stitch
User that the function executes as. Cannot be used with
run_as_user_id . |
||||||||
respond_result Boolean
|
If true , Stitch includes the webhook function return value as
the body of the HTTP response it sends to the client that
initiated the webhook request. |
||||||||
options Document
|
A document that contains configuration options for the webhook.
|
Source Code¶
Triggers¶
Triggers are defined in your application’s
/triggers
directory.
Each trigger is defined in its own JSON file with the same name as the trigger.
Configuration¶
Field | Description |
---|---|
id String
|
A string that uniquely identifies the trigger. Stitch automatically generates a unique ID for a trigger when you create it. |
name String
|
The name of the trigger. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens. |
type String
|
The type of application event that the trigger listens for. Valid Options:
|
function_name String
|
The name of the Stitch function that the trigger
executes whenever it fires. The trigger automatically passes
arguments to the function depending on the trigger type . |
config Document
|
A document with fields that map to additional configuration
options for the trigger. The exact configuration fields depend on
the trigger |
disabled Boolean
|
If true , the trigger will not listen for any events and will
not fire. |
Hosting¶
Files that you want to host on Stitch should be
included in your application’s /hosting
directory. Each file
will be uploaded with the metadata defined in metadata.json
.
You can configure the metadata for each hosted file in
metadata.json
. This metadata configuration file is an array of
documents that each correspond to a single hosted file’s metadata
attributes.
Metadata Configuration¶
Field | Description | ||||||
---|---|---|---|---|---|---|---|
path String
|
The resource path of the file. | ||||||
attrs Array<Document>
|
An array of documents where each document represents a single metadata attribute. Attribute documents have the following form:
|
Note
If you do not specify a Content-Type
attribute for a file, Stitch
will attempt to automatically add a Content-Type
attribute to it
based on the file extension.
For example, Stitch would automatically add the attribute
Content-Type: application/html
to the file myPage.html
.
Values¶
Values are defined in your application’s /values
directory.
Each value is defined in its own JSON file named after the value.
Configuration¶
Field | Description |
---|---|
id String
|
A string that uniquely identifies the value. Stitch automatically generates a unique ID for a value when you create it. |
name String
|
A unique name for the value. This name is how you refer to the value in functions and rules. |
from_secret Boolean
|
Default: false . If true , the value exposes a
Secret instead of a plain-text JSON value. |
value String, Array, or Object
|
The stored data that Stitch exposes when the value is referenced. If If |