Connecting to the API

To connect to our API, you can either connect through GraphiQL or by using generated API Access Keys in your scripts.

1. Table of Contents

• GraphQL
• Development Tools
• API Keys Authorization

2. GraphQL

To learn how to use our API, we strongly recommend using a GUI, which helps you edit and test GraphQL queries and mutations. Learn more about GraphQL here.

GraphiQL

GraphiQL is by far most popular GUI for GraphQL schemas, it is available on macOs, Linux, or Windows and can be installed by following the instructions from the GraphiQL ElectronJs website.

Using GraphiQL

GraphiQL contains four main sections:

• Input - type the queries or mutations to run against our platform
• Variables - variables to use in queries or mutations
• Output - the result of queries or mutations
• Docs - browse through the GraphQL schema for documentation on fields and types

Take a look at the Core Concepts section to see a list of common queries and mutations that can help you get started with our API.

3. Development Tools

You can use GraphiQL to connect to our API and view the GraphQL schema documentation while performing queries and mutations against our endpoint.
To authorize a connection to our API through the UI:

1. Browse to your OWNZONES environment login page.
2. Fill in the Username and Password fields, then click Sign In.
3. Fill in the Verification Code from your MFA Authenticator app, then click Submit.
4. Open the DevTools pane (F12) and, on the Network tab, in the Filter field, type graphql.
5. Click the request with the Status of 200 and then copy the following information:
6. General > Request URL - the API gateway;
7. Request Headers > Authorization - the temporary authorization token;
8. Request Headers > X-Organization-Slug - the slug of the organization;
9. In GraphiQL, set the following:
10. GraphQL Endpoint - fill in with the previously copied API gateway;
11. Method: POST
12. Add the authorization header (Edit HTTP Headers > Add Header):
    • Header name: Authorization
    • Header value: paste the value of the previously copied authorization token (including the Bearer keyword);
13. Add the organization slug header (Edit HTTP Headers > Add Header):
    • Header name: X-Organization-Slug
    • Header value: paste the value of the previously copied organization slug parameter.

4. API Keys Authorization

Any complex scenario requires the use of the API Keys.

Retrieving API Keys and HTTP Headers

To retrieve API Keys and HTTP Header names for access to our API:

1. Browse to your OWNZONES environment login page.
2. Fill in the Username and Password fields, then click Sign In.
3. Fill in the Verification Code from your MFA Authenticator app, then click Submit.
4. After selecting the organization, copy its slug from the URL of the page, dirrectly following the environment URL: https://connect.ownzones.com/ORGANIZATION-SLUG.
5. From the top-right corner, on the Profile Options drop-down, click Debug.
6. Open the DevTools pane (F12) and, on the Network tab, in the Filter field, type graphql.
7. Click the request with the Status of 200 and then copy the value from the General > Request URL, which represents the the API gateway.
8. From the top-right corner, on the Profile Options drop-down, click Edit Account.
9. Click New API Key.

   Note: If you can't see the New API Key button, ask your System Administrator to grant you permission to generate API keys.

10. Fill in the Name field and choose an Expiration Date, then click Save.

    Note: Write down the secret key, as this is the only time you can access it.

Connecting through API Keys

To authorize a connection through API keys, you must create a function that generates a digital signature based on the secret key you obtained, then use the signature when making requests to the GraphQL Endpoint.

Create Signature

const hmac = crypto.createHmac('sha256', secretKey);
hmac.write(JSON.stringify(payload));
hmac.end();

const signature = hmac.read().toString('hex');

GraphQL Response

Create a response that takes into account the public key, organization slug, signature, and graphql request body:

const response = await fetch(`https://${endpoint}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Organization-Slug': orgSlug,
    'oz-key-id': publicKey,
    'oz-signature': signature
  },
  body: JSON.stringify([{
    query,
    variables,
  }]),
});