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
  • 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 should be placed in the root of your StepZen schema folderm at the same level as your index.graphql.

my-stepzen-folder
    .
    ├── 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:

configurationset:
  - configuration:
      name: api_config
  - configuration: 
      name: database_config
  • configurations 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 you choose.

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 (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:

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

Passing Additional Header Values

Some APIs require 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 prepending header. to the key name.

configurationset:
  - 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

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

A full example for the dsn portion could be:

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:

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

The uri value can include the following parameters:

uriValueDescriptionExample
usernameUsername is usernamelucy
passwordPassword in passwordmysecretpassword
addressAddress in addressaddress.from.deployment.service
dbnameDatabase name in dbnamemydbname
postgresql://You can leave the postgresql://part of the uri as it is

A full example for the dsn portion could be:

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 enables you to keep API keys and DSN information within environment variables. For example, in a .env file, but 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 stored 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 could then reference the value of STEPZEN_MYSQL_DSN within a configuration inside config.yaml:

configurationset:
  - configuration:
      name: mysql_config
      dsn: STEPZEN_MYSQL_DSN

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. 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 would 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 when running an @sequence directive, GraphQL arguments can be passed as header variables in an HTTP request. Take the example below, where 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 contains 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 being sent as headers.

Combining Variables with Strings in Authorization headers

StepZen also supports strings combined with variables in header parameters.

As shown in the schema, 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/ will still send the Authorization header the same way it did previous, "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 the 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,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 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
    @connector(
      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 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.