Manage Configuration and Keys

Configure your API keys and database connections in StepZen

For StepZen to properly access the data in your backends, you'll need to manage things like usernames, passwords, DSNs, authorizations and other values and pass these to the appropriate connector (i.e. @rest or @dbquery). These are managed in a single file named config.yaml.

The config.yaml file should be placed in te root of your StepZen schema folder at the same level as your index.graphql.

    ├── index.graphql
    ├── config.yaml
    └── schemas

What's a config.yaml?

Your config.yaml is a file written in YAML to relay information regarding your configuration and keys to StepZen While a config.yaml is not always required for a schema to work, you'll generally need this file when using a REST service, a database, a template or the @connector directive.

What you specify in your config.yaml may differ depending on the connection type, but there are a few lines you will always need:

  - configuration:
      name: api_config
  - configuration: 
      name: database_config
  • configurationset is the parent that contains the full set of configurations.
  • configuration defines a new configuration.
  • name is the name of your configuration. This can be anything of your choice.

REST Configurations

If a REST service is public and you do not need an API key, you may not need a configuration. However, you can still use configurations to pass any values into @rest. For example, the following configuration contains a username key.

  - configuration:
      name: dev_config
      username: remotesynth

This configuration value can be used when constructing the endpoint URL as in the following query:

type Query {
  myArticles: [Article]
      endpoint: "$username"
      configuration: "dev_config"

In this case, the value of $username will be replaced with the value of username from dev_config (i.e. remotesynth).

Passing an API key via the Authorization header

If a REST service requires an API key that is passed using the Authorization header, you can pass it via the Authorization key of the config:

  - configuration:
      name: github_config
      Authorization: Bearer MY_PERSONAL_ACCESS_TOKEN

Passing Additional Header Values

Some APIs require that you pass API keys or other values in the header via other named keys other than the Authorization header. You can pass these in the header by appending header. to the key name.

  - configuration:
      name: dev_config
      header.api-key: MY_API_KEY

Database Configurations

StepZen currently supports connection to both MySQL and PostGreSQL databases. Each of these require a slightly different type of configuration.

MySQL Configuration

For MySQL databases, you'll need to pass the DSN that contains the connection information for that MySQL database.

- configuration:
    name: mysql_config
    dsn: username:password@tcp(a.b.c.d:port)/dbname

In this the dsn value

  • username is the username of the database user required for access
  • password is the database password associated with that username
  • a.b.c.d:port is the host and port specification
  • dbname is the MySQL database name

For example:

dsn: john:secretpassword@tcp(us.address.from.deployment.service:8090)/mydbname

Postgres Configuration

For a PostgreSQL database connection, you'll need to provide a URI in a format like the following:

  - configuration:
    name: pg_config
    uri: postgresql://username:password@address/dbname

The uri is made up of the following

  • username is the username of the database user required for access
  • password is the database password associated with that username
  • address is the host/port information to connect to your database
  • dbname is the name of the database you'd like ot connect to

For example:

uri: postgresql://lucy:mysecretpassword@address.from.deployment.service/mydbname

Environment Variables

You can leverage values stored in environment variables within your StepZen config.yaml file. This allows you to keep API keys and DSN information within environment variables (for example, in a .env file) but still leverage them within your schema configuration. The only rule is that the environment variable name must be prefaced with a STEPZEN_.

For example, imagine you stored the DSN information or a MySQL connection within a .env file as follows:


You could then reference the value of STEPZEN_MYSQL_DSN within a configuration inside config.yaml:

  - configuration:
      name: mysql_config

This doesn't just apply to DSN configuration. You can use environment variables in place of API keys as well.

For templates

If you're using a StepZen template, you'll be prompted to provide the necessary connection details via the command line during the template installation process and your config.yaml will be auto-generated for you.

For example, if you run stepzen import fedex to import the FedEx API template, you'll be prompted with the following questions via the commmand line:

? What is the account number to your FedEx account? [hidden]
? What is the password to your FedEx account? [hidden]
? What is the API key to your FedEx account? [hidden]
? What is the meternumber to your FedEx account? [hidden]

The generated config.yaml would look like the following:

  - configuration:
      name: fedex_config
      accountnumber: {{YOUR_ACCOUNT_NUMBER_HERE}}
      password: {{YOUR_PASSWORD_HERE}}
      key: {{YOUR_KEY_HERE}}
      meternumber: {{YOUR_METERNUMBER_HERE}}

It's important to note that the CLI does not validate your responses. However, if you make a mistake, you can simply modify the config.yaml - you do not need to rerun the import.

The @connector Directive

The @connector directive is used to configure the out-of-the-box StepZen connectors. You may encounter them when you importing some of StepZen's API templates via stepzen import .

For example, say you ran stepzen import ipapi and you see @connector in your locationIpApi.graphql:

type Query {
  location(ip: String!): Location
      type: "__ipapi_location_ip_connector__"
      configuration: "ipapi_default"

Behind the scenes, this connector is using a pre-configured connection to the IP-API that StepZen provides based on a fixed GraphQL schema. This means that StepZen handles the configuration for you, so you don't need to worry about what you put in your config.yaml.

Of course, if you have a subscription to the IP-API that you would like to use, you could add a config.yaml and referencing it in place of the default configuration, but you don't have to do that in order to get the schema working.

This site uses cookies: By using this website, you consent to our use of cookies in accordance with our Website Terms of Use and Cookie Policy.