Manage Configuration and Keys

Configure your API keys and database connections in StepZen

For StepZen to properly access the data in your backends, you need to manage things like:

  • Usernames
  • Passwords
  • DSNs
  • Authorizations
  • Other values

You pass this information to the appropriate connector (i.e., @rest or @dbquery). These are managed in a single file named config.yaml.

The config.yaml file must be placed in the root of your StepZen schema directory, at the same level as your index.graphql file:

my-stepzen-folder
    .
    ├── index.graphql
    ├── config.yaml
    └── schemas

What's a config.yaml?

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:

configurationset:
  - configuration:
      name: api_config
  - configuration: 
      name: database_config
  • configurations: Parent that contains the full set of configurations.
  • configuration: Defines a new configuration.
  • name: Name of your configuration. This can be anything you choose.

The following subsections provide additional details about config.yaml files:

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:

configurationset:
  - 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]
    @rest(
      endpoint: "https://dev.to/api/articles?username=$username"
      configuration: "dev_config"
    )
}

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

Pass an API key via the Authorization Header

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

configurationset:
  - configuration:
      name: github_config
      Authorization: Bearer MY_PERSONAL_ACCESS_TOKEN

Pass Additional Header Values

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

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

Database Configurations

StepZen currently supports connections to MySQL, PostgreSQL, and MSSQL databases. MySQL and PostgreSQL require a slightly different type of configuration as described in the following subsections:

MySQL Configuration

For MySQL databases, you must 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

The dsn value can include the following parameters:

dsn ValueDescriptionExample
usernameYour usernamejohn
passwordYour MySQL database passwordsecretpassword
a.b.c.d:portYour host and port specificationtcp(us.address.from.deployment.service:8090)
dbnameYour MySQL database namemydbname

The example shows the dsn portion:

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

Postgres Configuration

For a PostgreSQL database connection, you must provide a URI in a format like the following:

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

The uri value can include the following parameters:

uriValueDescriptionExample
usernameYour usernamelucy
passwordYour passwordmysecretpassword
addressService Addressaddress.from.deployment.service
dbnameYour Postgres database namemydbname
postgresql://You can leave the postgresql://part of the URI as it is

The following shows a full example for the dsn portion:

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

MSSQL Configuration

For MSSQL databases, you must pass the DSN that contains the connection information for that MSSQL database:

configurationset:
  - configuration:
      name: mssql_config
      dsn: "sqlserver://username:password@host:port?database=dbname"

Note: : is optional. The default port is 1433.

The dsn value can include the following parameters:

dsnValueDescriptionExample
usernameYour username.Lucy
passwordYour password.Mysecretpassword
hostHost name or IP address.localhost
portHost port.1433
databaseYour MSSQL database name.Mydbname

The following shows an example for the dsn portion:

dsn: sqlserver://:@:?database=Mydbname; username=Lucy; password=Mysecretpassword

Environment Variables

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

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

STEPZEN_MYSQL_DSN=username:password@tcp(us-cdbr-east-03.cleardb.com)/database_name

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

configurationset:
  - configuration:
      name: mysql_config
      dsn: STEPZEN_MYSQL_DSN

Note: This doesn't just apply to DSN configurations. 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. Your config.yaml will then be auto-generated.

For example, if you run stepzen import fedex to import the FedEx API template, you'll be prompted with the following questions via the command 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 file will look like the following:

configurationset:
  - 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 re-run the import.

Authorization Headers in the GraphQL Schema

In some cases, such as when running a @sequence directive, GraphQL arguments can be passed as header variables in an HTTP request. In the example below, an argument of access_token: String is passed to the authorization header as a bearer token:

type Query {
    id: String 
}

type Query {
    my_query(access_token: String): Query
        @rest (
            endpoint: "https://api.example.com/v1/api/"
            headers: [{ name: "Authorization", value: "$access_token" }]
        )
}

Query

When running the GraphQL query, the access_token: String argument is "Bearer <YOUR_ACCESS_TOKEN>" where <YOUR_ACCESS_TOKEN> must be replaced by your own access token, and contain the entire string for the Authorization header:

query MyQuery {
  my_query(
    access_token: "Bearer <YOUR_ACCESS_TOKEN>"
  ) {
    id
  }
}

If there is no access_token provided in the query, StepZen recognizes the null parameter and will resolve the Authorization header to an empty string, "".

This is an example query where there is no access_token argument provided:

query MyQuery {
  my_query {
    id
  }
}

Authorization: "null" is converted to Authorization: "" to prevent errors from the server and keeps unwanted null parameters from being sent as headers.

Combine Variables with Strings in Authorization Headers

StepZen also supports strings combined with variables in header parameters.

As shown in the schema below, my_query will combine the argument access_token with Bearer:

my_query(access_token: String): Query
        @rest (
            endpoint: "https://api.example.com/v1/api/"
            headers: [{ name: "Authorization", value: "Bearer $access_token" }]
        )

When my_query is executed, access_token does not need to contain the Bearer string. The schema combines the Bearer string with the access_token:

query MyQuery {
  my_query(
    access_token: "CMORsM63LxIO_4eBAEBAgAAMAEAAAAYY_MDnCSCXsaQLKM_AFzIUdnIEl9qo7Cwj2t1Z_rNAec5zYls6LgB_b8f_BwyE_wf8_-D_fc4sAAAAYAYY9DwfIBgcgA_gwx8GGQAAOIUnAADgAOBCFBZjpguluSl9IBk0ni7_U1o-pPgjSgNuYTFSAFoA"
  ) {
    id
  }
}

The request going to the endpoint https://api.example.com/v1/api/ still sends the Authorization header the same way it did previously ("Authorization": "Bearer CMORsM63LxIO...").

@Sequence Example of Passing access_token as a Variable

Let's say there is an @sequence that sends the_access_token but does not provide the token type Bearer in the string.

Note: Refer to the @sequence documentation to understand how this sequence passes variables between queries.

You do not need to understand @sequence in full detail to know how StepZen uses the access_token to support Authorization headers in this example.

type Auth {
    access_token: String!
    token_type: String!
    expires_in: String!
}

type Query {
    id: String 
}

type Query {
    get_auth: Auth
        @rest(
            method: POST
            contenttype: "application/x-www-form-urlencoded"
            endpoint: "https://api.example.com/v1/api?username={{.Get \"username\" }}&password={{.Get \"password\" }}"
            configuration: "configs"
        )
    my_query(access_token: String): Query
        @rest (
            endpoint: "https://api.example.com/v1/api/"
            headers: [{ name: "Authorization", value: "Bearer $access_token" }]
        )
    """
    returns a query with the new access_token
    """
    query_with_key: Query
        @sequence(
            steps: [
                { query: "get_auth" }
                { query: "my_query" }
            ]
        )
}

type Auth has the field access_token, and in the query_with_key @sequence, the get_auth query passes the access_token to the my_query query.

{
    "token_type": "bearer",
    "refresh_token": "12314-3ee9-4a6b-bc87-134254332",
    "access_token": "CMORsM63LxIO_4eBAEBAgAAMAEAAAAYY_MDnCSCXsaQLKM_AFzIUdnIEl9qo7Cwj2t1Z_rNAec5zYls6LgB_b8f_BwyE_wf8_-D_fc4sAAAAYAYY9DwfIBgcgA_gwx8GGQAAOIUnAADgAOBCFBZjpguluSl9IBk0ni7_U1o-pPgjSgNuYTFSAFoA",
    "expires_in": 21600
}

As shown above, access_token generated by the first step (using get_auth), does not have Bearer preceding the token generated, so my_query must be written with headers: [{ name: "Authorization", value: "Bearer $access_token" }]. StepZen combines the variable access_token being passed in the first step with Bearer added in the schema to properly execute the Authorization header.

my_query(access_token: String): Query
        @rest (
            endpoint: "https://api.example.com/v1/api/"
            headers: [{ name: "Authorization", value: "Bearer $access_token" }]
        )

The @connector Directive

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

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

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

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

If you have a subscription to the IP-API that you would like to use, you can add a config.yaml file and reference 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.