Using the API

The Optix API is GraphQL based and designed to provide you with the best possible experience. To support the use of our API, we provide two useful tools: the GraphQL Voyager and the GraphQL Playground.

More information on GraphQL and why we chose it is available in the Optix and GraphQL section.

Authentication

Tokens are authentication keys and are always associated with an app. They are used to identify the caller and restrict the data available via API.

Tokens are made available in the following ways:

On the ‘Develop → your app’ page in the Optix admin dashboard.
Via a webhook, delivered when an app is installed by an admin.

Each kind of token provides a different schema:

Organization token: Related to an organization, this token is intended for interactions NOT related to a user. Any interaction will be logged against the app, and all information retrieved will be based on the organization associated with this token.
Personal token: Related to a user, this token is intended for interactions on behalf of a user. Any interaction will be logged against the user, and all information retrieved will be based on the user/member/organization associated with this token.

Note

All tokens will expire from time to time. You should subscribe to the webhook “organization_token_updated” and update the token when you receive that webhook. You can find details on what to expect in the webhook here.

We support the Bearer authentication scheme, so you can do one of the following:

Include the header Authorization: Bearer TOKEN.
Add URI query parameter access_token=TOKEN.
Set body parameter access_token. This only works for POST requests with either application/x-www-form-urlencoded, or application/json Content-Type.

Note: Make sure to access the Optix GraphQL API using a valid access token, otherwise you will not see the full schema.

Tip

Organization tokens always end with an ‘o,’ while personal tokens always end with a ‘p.’

GraphQL Voyager Tool

This tool provides a map of all objects available to you. You can navigate and read the documentation for each field, and also visualize the connections between objects.

Launch Voyager tool

You can also access the Voyager through the link provided in the ‘Develop’ page of the Optix admin dashboard, using the organization or personal token menu item:

The menus in the admin dashboard in ‘Apps –> Develop –> your app’ where you’ll find links to launch the Voyager tool with your tokens pre-filled.

GraphQL Playground

This provides a debug tool and documentation during the creation of a GraphQL query. Feel free to explore all the objects and test out all the parameters available. Click ‘Docs’ on the right to pull out a section where you can find information to help understand each object. This demo allows you to read (‘Query’) data, but writing (via ‘Mutations’) is blocked.

Important

This tool provides different results depending on the token provided. It reads from our current public APIs (using GraphQL introspection) and provides the most up to date documentation possible.

Example

This example is a query that fetches the name and email of the currently logged in user. Click the play button to run it. You could try adding a new line after email and adding user_id to get a feel for how it works. You can also open this example in another tab if you like.

Hidden on mobile

This tool doesn’t fit on screens this small. Please use a browser which is a bit bigger (you could try rotating your phone).

In the above example playground, mutations (writing to the API) are disabled.

You can also access the playground through the link provided in the ‘Develop’ page of the Optix admin dashboard, using the organization or personal token menu item:

The menus in the admin dashboard in ‘Apps –> Develop –> your app’ where you’ll find links to launch the Playground tool with your tokens pre-filled.

Got questions?

We are here to help. Ask us a question and we’ll do our best to answer as soon as possible.

Building Your First App

Optix and GraphQL