API Authentication

To communicate with the GraphQL API, you must use generated API keys in your system integrations or applications.

Each API key is associated with an account. When generating an API key, it has the same access rights as the account used to generate it.

To limit access to your content, you should create a dedicated user account (service account) with specific access rights designed strictly for generating the API keys for your organization. For more information about creating a user role using custom policies, see the Custom Policies section on The Users / Permissions Tab.

Generate API Keys

To access our API, you have to generate API Keys and HTTP header names:

1. Log into your Connect environment.
2. Select your organization.
3. Copy its slug from the page URL, directly following the environment URL. For example, https://connect.ateliere.com/ORGANIZATION-SLUG. Note that you can also find the organization slug in the organization settings.
4. In the top right corner, click on your profile and select Edit Account.
5. Under the API Keys section, click New API Key. The Create Api Key modal is displayed. Note that if the New API Key button is not displayed, you must request permission to generate API keys from your organization administrator.
6. Enter a relevant name for your API key and choose an expiration date. We recommend you set a maximum one year expiration date for your API key.
7. Click Save. After saving, the secret and public keys are displayed.

HTTP Headers

When creating a GraphQL request, you must include the following mandatory headers:

• Content-Type

  The Content-Type header is a mandatory string representing the type of content requested: application/json.

• X-Organization-Slug

  The X-Organization-Slug header is a mandatory string representing the slug of the organization.

• oz-key-id

  The oz-key-id header is a mandatory string representing the public key.

• oz-signature

  The oz-signature header is a mandatory string representing the signature included in the request.

  Each request must use a signature based on the payload of the request. The signature is obtained by creating an HMAC code with a SHA256 hash function, using the secret key. The result is converted into a hex-encoded string.

  The payload of the HMAC function is a serialized object composed of the following parts:

  • the URL of the request, without the protocol. For example, "demo.ownzones.com/graphql".
  • the body of the request
  • the organization slug

Example Payload

payload = {
   url: url.replace(/^https?:\/\//, ''),
   body: body,
   organization_slug: organizationSlug,
 }

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

Additional Headers

Connect uses a built-in API usage tracking system that collects metrics data to understand how the API is used, proactively resolve performance bottlenecks and appreciate how clients can be affected by possible API changes.

A client awareness feature is also present and activated whenever the information about the client, be it an application or a system integration, sends its data by providing the following distinct HTTP headers with each API request:

• oz-client-name

  The oz-client-name header is an optional string representing the name of the client's application.

• oz-client-version

  The oz-client-version header is an optional string representing the client application version. Any value can be provided, for example, a numeric build number, a version codename, a SemVer string, etc.

  Note: If only the client name is provided, without including a version, all requests metric data will be aggregated under the same unidentified version group.

Example Request

const url = 'url_here';
const query = 'query_here';
const variables = 'query_variables_here';
const secretKey = 'secret_key_here';
const organizationSlug = 'organization_slug_here';
const publicKey = 'public_key_here';
const ozClientName = 'oz_client_name_here';
const ozClientVersion = 'oz_client_version_here';

const body = JSON.stringify([{
  query,
  variables,
}]);

const hmac = crypto.createHmac('sha256', secretKey);
const payload = {
  url: url.replace(/^https?:\/\//, ''),
  body: body,
  organization_slug: organizationSlug,
};
hmac.write(JSON.stringify(payload));
hmac.end();

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

const response = await fetch(`https://${payload.url}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Organization-Slug': organizationSlug,
    'oz-key-id': publicKey,
    'oz-client-name': ozClientName,
    'oz-client-version': ozClientVersion,
    'oz-signature': signature
  },
  body: body,
});

Additional Resources

This guide cannot cover all the details about GraphQL authorization. Here are some starting points to help you find more details:

• Official GraphQL documentation