In the world of modern GraphQL development with IBM API Connect for GraphQL (StepZen), integrating with backend services such as REST, GraphQL, or database endpoints is a common task. These integrations often require sensitive credentials like API keys, authorization tokens, or custom headers.

IBM API Connect for GraphQL enables developers to build unified GraphQL APIs quickly by importing existing data sources. However, when using the powerful stepzen import command, it’s easy to accidentally expose secrets in your GraphQL schema files.

That’s where the --secrets flag comes in. It ensures sensitive credentials are never written into generated schema files and are instead managed securely in your configuration.

Why You Must Use --secrets

Without --secrets, any header you pass to an import command—even a temporary test value—gets hardcoded into your .graphql file.

🚫 Example of What to Avoid 

# Exposed in your schema file!
type Query {
  myQuery: Root
    @rest(
      endpoint: "https://myapi.com/v1"
      headers: [{ name: "Authorization", value: "Bearer 12345-THIS-SECRET-IS-EXPOSED" }]
    )
}

stepzen import curl https://my-backend.com/api/v1/user \
  --header 'Authorization: Apikey 12345-THIS-IS-A-SECRET' \
  --secrets 'Authorization'

stepzen import graphql https://your-graphql-endpoint/graphql \
  --header 'X-API-KEY: MySuperSecretKey' \
  --secrets 'X-API-KEY'

configurationset:
  - configuration:
      # StepZen inserts the raw value here:
      authorization_416efbc0dc: Apikey 12345-THIS-IS-A-SECRET 
      name: curl_import_config

type Query {
  myQuery: Root
    @rest(
      endpoint: "https://my-backend.com/api/v1/user"
      # The value is now a secure variable reference!
      headers: [{ name: "Authorization", value: "$authorization_416efbc0dc" }]
      configuration: "curl_import_config"
    )
}

stepzen import graphql https://example.com/graphql \
  --header 'Authorization: Apikey 1234' \
  --header 'token: my-token-value' \
  --secrets 'Authorization' \
  --secrets 'token'