Before You Start

As mentioned in Intro to GraphQL, an example ping query to the Fluz API looks like this:

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: <base64_encoded_api_key>' \
--data '{"query":"query Marco {\n  marco\n}"}' \
https://transactional-graph.staging.fluzapp.com/api/v1/graphql

and will return a JSON payload with the following format:

{
  "data": {
    "marco": "polo"
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

This guide uses this example query and its response to provide guidance on using the Fluz API.

Headers

Lines 2 and 3 of our example ping query are headers. The Fluz API requires the following headers:

• Authorization
• Content-Type

Content Type

The Fluz API accepts and returns JSON. To call the Fluz API, you must pass a Content-Type header with the value of application/json.

Authorization

Fluz API requests are authenticated using Basic auth. Using Basic auth, your API Key is provided as the username, and a password is not required. API Keys are created in the Dashboard. To obtain an API Key, see Creating and Managing API Keys.

Once you have obtained an API Key, to make a request, pass an Authorization header with your base64 encoded API key:

'Authorization': 'Basic <base64_encoded_api_key>'

Requests with missing or invalid credentials will receive a 401 Unauthorized response code.

Alternatively, you can use a client like Postman for authorization using the following steps:

1. In Postman, create a new request.
2. Select the Authorization section.
3. Select Basic and pass your API key.

Basic Token

Basic Auth (or API Key) is used for the initial authentication step where the application needs to prove their identity to the server to act as the application. The API Key is assembled and base64-encoded string app_id:app_secret. For easier usage, this is also generated as api_key column in application table. To change the API Key, we can simply rotate the api_secret.

Usage

Request User Access Token: In the context of requesting user access tokens, Basic Auth is used to authenticate the user's credentials to issue a token that allows the application to act on behalf of the user.

Get Application Scopes: Get all the scoped granted on the App (Global) level.

Bearer Token

Usage

Using a Bearer Token, the application makes requests as if it is the user, with the same level of access that the user would have. This is essential for operations where the application needs to perform actions on behalf of the user based on the permissions granted to the user’s token.

Request Body

In our marco polo query example, the request body is displayed on line 4. The Fluz API accepts POST requests with JSON payloads. Requests must contain a string named query, but can also contain variables and operationName.

The query is the GraphQL operation that you are calling:

{
  "query": "{ marco }"
}

You can make multiple GraphQL requests in a single call. In this case, you would still provide a single query value with multiple calls as a string.

Request URLs

Our example marco polo query has a request URL on line 5. Request URLs used for the Fluz API differ depending on whether you use the live or test environments.

The live and test environment both use a graphql endpoint, with a different subdomain:

Test Environment Request URL
https://transactional-graph.staging.fluzapp.com/api/v1/graphql

Live Environment Request URL
https://transactional-graph.fluzapp.com/api/v1/graphql)

Status Codes

In GraphQL, unlike REST APIs, you'll often receive a 200 OK status code even for error situations. For error handling, the response includes an errors object with detailed information for troubleshooting. For mutations, request the userError type on the union type for specific details about the failure. See error handling for more information.

There are a few non 200 status codes that Fluz’s GraphQL API returns for the following cases:

Response Bodies

📘

Read more about GraphQL responses and formats in the spec.

The response body of a query contains the data requested from the API endpoint. The Fluz API returns JSON response bodies. Response bodies contain the following:

If you need help with a response, see troubleshooting with request IDs in the Fluz API.