Connect to StepZen

How to get your endpoint URL and API key, and use API testing tools like Postman.

After your API is up and running, you will likely want to connect to it via your application's frontend or an API testing tool like Postman. To do so, you'll need to use your StepZen API key, available on your StepZen dashboard.

The following subsections explain how to obtain and use the API key:

Get Your Endpoint URL

First, create your working directory and run stepzen init inside it to initialize a StepZen workspace.

The stepzen start command makes a browser with a GraphiQL editor available for testing your API. The editor has a connection to the project deployed on StepZen. It also provides you with the URL required to connect to your API via your frontend application or API testing tool. This URL can be found in two places:

The bottom-right-hand side of the GraphiQL editor available at your localhost URL:

As output from the stepzen start command:

Your API url is  https://username.stepzen.net/api/harping-cat/__graphql

The sections below show how to use that endpoint in your frontend or via popular API testing tools.

You can see a full list of all the APIs you've deployed to StepZen by running stepzen list schemas from the command line.

Get Your StepZen API Key

Use your API key to connect to StepZen from outside of the GraphiQL editor launched by stepzen start. This is always accessible via your StepZen dashboard, which has three items:

Your account name: Your endpoint URL always starts with your account name in the format: https://{ACCOUNT}.stepzen.net.
Your admin API key: Enables you to make changes to your account, such as deploying new or updated code to StepZen. Enter this key when logging into the StepZen CLI to enable commands like stepzen start to automatically deploy your API and connect to it.
Your API key: Required to connect to the APIs you deploy to StepZen. Pass this key when querying your APIs – through code or an API testing tool – via the Authorization header in the following format:

Authorization: apikey {APIKEY}

The following sections show some examples of connecting to a StepZen API.

Call Your StepZen API From JavaScript

It's important that you do not expose your API key publicly. Therefore, you must not call your StepZen API directly from the browser as anyone could inspect the request and gain access to your API key. Instead, invoke the API call on the server or via a serverless function, both of which can be written in Node.js.

An example using fetch() will look like this:

fetch('https://{ACCOUNT}.stepzen.net/api/example/__graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'apikey {APIKEY}',
  },
  body: JSON.stringify({query: '{QUERY}'}),
})
  .then(response => response.json())
  .then(data => {
    console.log('Success:', data)
  })

In the above you need to add your own StepZen endpoint and GraphQL query.

Connect Using API Testing Tools

Although stepzen start provides a very helpful GraphiQL editor for testing your API, you may want to use some other popular tools:

Postman

Follow the steps below to set up Postman to connect to your StepZen GraphQL API:

Select the Authorization option beneath the endpoint URL.
Set Type to API Key.
Populate the options as follows, replacing {APIKEY} with your actual API key:
- Key: Authorization
- Value: apikey {APIKEY}
- Add to: Header

Postman should look as follows:

Setting up Postman

Add your GraphQL query under Body > GraphQL.

GraphQL Playground

GraphQL Playground is a popular desktop GraphQL IDE.

Follow the steps below to set up GraphQL Playground to connect to your StepZen GraphQL API:

Open a new workspace using a URL endpoint in the following format:

https://{ACCOUNT}.stepzen.net/api/example/__graphql

Click on the HTTP Headers tab at the bottom of the Playground, and configure your API Key as follows, replacing {APIKEY} with your actual API key:
```
{
  "Authorization": "apikey {APIKEY}"
}
```
The GraphQL Playground should look as follows:

Now you can inspect and query your GraphQL endpoint running on StepZen.