Start using the GraphQL API

Generally, you will want to enable an application to communicate with the Cleverbridge GraphQL API. To do so, integrate our implicit authentication flow into your application by completing the following:

1. Decide what type of client you would like to use to request and receive access tokens from our identity server.
2. Register to use the CleverbridgeGraphQL API. To do so, contact Client Experience and provide them with the following information:
   • ID of your client application (client_id) that you will be using to communicate with our identity server

     Warning

     This is NOT your Cleverbridge client account ID (client_id).

   • Your redirect URL
   • Your postlogout URL
3. Set up your client application to authenticate using the OpenId Connect implicit flow. To do so, you need the information that you provided in step 2, and the information that you received from Cleverbridge after your registration. This includes:

   Field	Value
   authority	https://identity.cleverbridge.com
   scope	openid GQL cb_useraccount.profile

   For a full description of the OpenId Connect implicit flow, see Implicit Flow.

4. Test the authentication process using your client application. If you have any questions during this process, contact Client Experience.

In certain situations, you may want to enable your back-end to communicate directly with the Cleverbridge GraphQL API. To do so, integrate our client-credential authentication flow into your back-end by completing the following:

1. In the Commerce Assistant, go to Setup > Add User and set up a Cleverbridge user specifically for authentication purposes:
   • Enter a Username in the format <clientname>.GQL.<context>.
   • Select the API User privilege for the user.
   • Set up one user for each context in which you will use the GraphQL API.

   Example

   Shieldware Inc. uses the GraphQL API for monitoring purposes. They set up a new user in the Commerce Assistant, naming it Shieldware.GQL.Monitoring.

   For more information on how to set up users, see Users ✱.

2. Contact Client Experience and provide them with the name of the Cleverbridge user that you will use to authenticate.
3. Assign any additional privileges to your Cleverbridge user that you may need for your API calls. For example, if your back-end needs to access purchase information, you or your administrator should assign a privilege that provides full access to purchase-related features. For more information, see Privileges ✱.
4. Set up your back-end to authenticate using the client-credential flow. To do so, you need to send an HTTP POST request to the Cleverbridge IDentity server using the following information:

Note

Get your Access Token at the following endpoint:

https://identity.cleverbridge.com/connect/token

Field	Value
grant_type	Use the fixed value client_credentials to authenticate.
client_id	The username for the Cleverbridge user that you are using to authenticate. Warning This is NOT your Cleverbridge client account ID (client_id).
client_secret	The password for the Cleverbridge user that you are using to authenticate.
scope	GQL

There are two ways to request a token:

1. Send the credentials in an HTTP POST body

   Request Header

   Content-Type: application/x-www-form-urlencoded

   Request Body

   grant_type=client_credentials&scope=GQL&client_id=myOidcClient&client_secret=xxxxxx

2. Send the credentials in an HTTP POST Basic Auth header

   Request Headers

   Content-Type: application/x-www-form-urlencoded

   Authorization: Basic xxxxxxxxxxxxxxxxxxxxxx

   Request Body

   grant_type=client_credentials&scope=GQL

   Note

   With Basic Auth, the client_id is used as the username and the client_secret is used as the password.

If authenticated, the Cleverbridge IDentity server responds with an access token in JSON Web Token (JWT) format:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjNmMWI0MTc1OGU0NzM3ZmI[...]",
  "expires_in": 3600,
  "token_type": "Bearer"
}

5. Test the authentication process using your back-end. If you have any questions during this process, contact Client Experience.

One method of integrating with the Cleverbridge GraphQL API is building a browser-based JavaScript client application. For an example of how to build such an application, see Adding a JavaScript client.

Another method of integrating with the Cleverbridge GraphQL API is using a ReactJS app. There are a number of open-source tools that you can use to build this connection, including react-openidconnect and redux-oidc.

One method of integrating the Cleverbridge GraphQL API into your back-end is using an HTTP client for PHP. The example below uses the PHP library Guzzle.

<?php
$username = Shieldware.GQL.SubscriptionManagement;
$password = test123!;
$query = 'query subParam($id: Int!){
  subscription(id: $id) {
    id
    extraParameters {
      key
      value
    }
  }
}';
$subscriptionid = 23431030;
$arguments = ['id' => $subscriptionid];

public function graphql($username, $password, $query, $arguments = null)
{
  //Send a login request to the Cleverbridge IDentity server. Use the username and password of the Cleverbridge user that you set up for GraphQL authentication.
  $client = new GuzzleHttp\Client(['base_uri' => 'https://identity.cleverbridge.com']);
  $request = ['headers' => ['Accept' => 'application/x-www-form-urlencoded'], 'form_params' => ['grant_type' => 'client_credentials', 'client_id' => $username, 'client_secret' => $password]];
  //Retrieve the access token returned by the identity server upon successful authentication and authorization.
  try
  {
    $response = $client->request('POST', '/connect/token', $request);
  }
  catch(GuzzleHttp\Exception\RequestException $e)
  {
    if ($e->hasResponse())
    {
      $body = $e->getResponse()
        ->getreasonPhrase();
      $message .= PHP_EOL . 'Response: ' . $body;
    }
    return false;
  }
  $token = json_decode($response->getBody()
    ->getContents())->access_token;
  if (!isset($token))
  {
    $message .= PHP_EOL . 'Token not generated';
    return false;
  }

  //Send a request to the GraphQL server, passing the access token in the Authorization header. Define separate variables for the query string and the arguments associated with the query.
  $client2 = new GuzzleHttp\Client(['base_uri' => 'https://graph.cleverbridge.com']);
  $request = ['headers' => ['Authorization' => 'Bearer ' . $token, 'Content-Type' => 'application/json', 'Accept' => 'application/json', ], 'body' => json_encode(['query' => $query, 'variables' => $arguments]) ];
  $message .= PHP_EOL . $request['body'];

  //Retrieve the response returned by the GraphQL server upon successful validation of the access token.
  try
  {
    $response = $client2->request('POST', '/graphql', $request);
  }
  catch(GuzzleHttp\Exception\RequestException $e)
  {
    if ($e->hasResponse())
    {
      $body = $e->getResponse()
        ->getreasonPhrase();
      $message .= PHP_EOL . 'Response: ' . $body;
    }
    return false;
  }
  $response = json_decode($response->getBody()
    ->getContents());
  if (isset($response->errors))
  {
    $message .= PHP_EOL . 'Response: ' . $response->errors[0]->message . ' ' . $response->errors[0]->code;
    return false;
  }
  return $response;
}
?>

To authenticate your requests to the GraphQL API, you must pass the generated access token with each request. The GrapQL API uses OAuth 2.0 for authentication and authorization, and the Bearer authentication scheme. Here is an example of what a request looks like:

curl --location --request POST 'https://graph.cleverbridge.com/graphql' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjNmMWI0MTc1OGU0NzM3ZmI[...]' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query {        subscription(id: 23431030) {            id            extraParameters {                key                value            }        }}","variables":{}}'

Our GraphQL server validates the access token. If the server finds the access token to be valid, the request is allowed to proceed. Requests made with an invalid token receive a 401 Unauthorized error code.

The Cleverbridge GraphQL API uses conventional HTTP response codes to indicate success or failure of an API call. In general:

• Codes in the 2xx range indicate that the function call was successful.
• Codes in the 4xx range indicate an error that resulted from an incorrectly specified request (for example, a required parameter was missing or the data type passed in a parameter was incorrect).
• Codes in the 5xx range indicate an error on the Cleverbridge side.

When an individual IPv4 address or IPv6/64 IP range exceeds the per-second request limit, further requests to our API are blocked with an HTTP 429 status code until the block time has expired. This happens after one minute. The HTTP response contains a Retry-After header to indicate when you can resume sending requests.

HTTP/1.1 429 Too Many Requests
Content-Type: text/html
Retry-After: 60

The most likely cause of an HTTP 429 Too Many Requests error is that you perform a batch operation that sends multiple API requests in parallel. To avoid reaching the rate limit with batch operations, observe the following best practices:

• Send API requests in serial and not in parallel, that is the next call included in the batch operation cannot be made until the current call is completed.
• Limit concurrent threads that make requests (across all processes and machines) to a maximum of four.