Setting up your environment

Get your account information

Contact your API Connect for GraphQL administrator for the account name, the domain, and the keys.

Your administrator provides the following keys for your account:

  • Account name: Your organization shares a single account, which serves as a user name when you log in.

  • Domain: The domain where API Connect for GraphQL is installed, which you specify when you log in.

  • Admin key: Grants access to upload, modify, configure, and deploy APIs.

    When you log in to API Connect for GraphQL, you will be prompted for the admin key instead of a password.

  • API key: Grants access to consume GraphQL APIs and query the endpoints.

    The API key is required for connecting to the APIs deployed to API Connect for GraphQL. Pass this key through the Authorization header in the following format:

    Authorization: apikey {APIKEY}

Install the CLI

Use the CLI (command-line interface) to work with API Connect for GraphQL and your GraphQL APIs. The CLI is supported on Windows, Mac, and Linux.

  1. Install the Node.js runtime.

    Node is required for running the CLI.

  2. Install the CLI by running the following command:
    npm install -g stepzen

    If you receive EACCES errors with installing globally, see the Resolving EACCES permissions errors when installing packages globally in the Node documentation.

  3. (Optional) Customize the default CLI configuration as explained in Configuring the CLI.

Log in to API Connect for GraphQL using account name

API Connect for GraphQL does not provide a graphical UI. Instead, you use the CLI to work with the service.

  1. Log in by running the following command:
    stepzen login <domain> -a <account>

    where:

    • <domain> is the domain or the region where API Connect for GraphQL is installed or hosted. For example, eu-central-a.ibm.stepzen.net or us-east-a.ibm.stepzen.net
    • <account> is the username of the account you want to log in to.

    For example, if the environment name (account) is production, and the domain is envname.us-east-a.ibm.stepzen.net, then the login command looks like the following example:

    stepzen login envname.us-east-a.ibm.stepzen.net -a production
    Consider another example where the environment name (account) is beaverdam and API Connect for GraphQL is hosted in the envname.eu-central-a.ibm.stepzen.net region. In this scenario, the login command is: 
    stepzen login envname.eu-central-a.ibm.stepzen.net -a beaverdam
  2. When prompted, enter the admin key for the account.
The CLI logs in to the following URL: 
https://<environment_name>.<domain>
For example: 
https://envname.us-east-a.ibm.stepzen.net

Log in to API Connect for GraphQL using instance ID

API Connect for GraphQL does not provide a graphical UI. Instead, you use the CLI to work with the service.

  1. Log in by running the following command:
    stepzen login <domain> -i <instance_id>

    where:

    • <instance_id> is the ID of your service instance associated with your subscription.
    • <domain> is the domain or the region where API Connect for GraphQL is hosted. For example, eu-central-a.ibm.stepzen.net or us-east-a.ibm.stepzen.net

    For example, if the instance_id is 20250420-0847-3668-7006-2138aaf44423, and the service instance is hosted in envname.us-east-a.ibm.stepzen.net, then the login command looks like the following example:

    stepzen login envname.us-east-a.ibm.stepzen.net -i 20250420-0847-3668-7006-2138aaf44423
  2. When prompted, enter the IBM SaaS Console API key for the account you are logging into. To generate an API key from the IBM SaaS Console, see Creating API keys.
    Note: To access IBM API Connect for GraphQL through the IBM SaaS Console, you must have one of the following roles: service owner, APICGQL admin, or APICGQL developer. To create an API key within the IBM SaaS Console, you must have at least the service admin or service user role.
The CLI logs in to the following URL: 
https://<environment_name>.<domain>
For example: 
https:///envname.us-east-a.ibm.stepzen.net/

Create a workspace directory for your project

When you are ready to starting building GraphQL APIs, change to the appropriate workspace directory to ensure your artifacts are stored in the correct location.

  1. Create a workspace directory where you will work on a particular project.

    Name the directory whatever you like.

  2. Change to the new workspace directory.

  3. Run the following command to initialize the workspace:
    stepzen init

Get your API endpoint URL

The API endpoint URL is based on your account name, domain, and API name.

  1. In your initialized workspace directory, run the following command:
    stepzen start
  2. Note down the API endpoint URL that displays in the response.

    For example, if your account name is production, your domain is example.com, and your API name is harping-cat, you will see the following output:

    Your API url is  https://production.example.com/api/harping-cat/__graphql

    When you deploy an API, it is uploaded to this endpoint.

(Optional) Install Docker for local development

For instructions on setting up Docker for use with API Connect for GraphQL, see Using Docker for local API development.