The Chain.io Portal (https://portal.chain.io) is backed by a fully functional GraphQL API that you can use to automate any account functions that you can do via the screens.

Exploring the Chain.io GraphQL API

Visit https://portal.chain.io/graphql to use the GraphQL explorer interface. You can browse all available functions and queries available under your user account.

Chain.io also maintains examples of how to accomplish common tasks at https://github.com/chain-io/portal-graphql-examples/

Getting an API Key

To request an API key, email support@chain.io and include the name of the workspace you'd like access to. You can also submit a support request through the help function within the portal.

Using your API Key

When support provides you with your API key, you'll receive two pieces of information, a CLIENT_ID and a CLIENT_SECRET. Do not share your secret with anyone or they will be able to access your data.

To utilize your API key, you need to follow 3 steps:

Grant your API key access to a workspace within the Chain.io portal (only do this once)
Exchange your API Key for an access token (do this repeatedly as your access tokens expire)
Send your access token in your GraphQL requests

Each step is described in detail here:

Granting API Keys Access To A Workspace

Within the Chain.io portal, API Keys work just like users. To grant an API key access to a workspace that you manage, simply create a new user with your CLIENT_ID and "@api.chain.io". The API key will have access rights based on the permission you grant in the user table.

If you'd like an API key to be able to access multiple workspaces, then add it to each one individually.

Exchanging Your API Key For An Access Token

Your CLIENT_ID and CLIENT_SECRET cannot access the GraphQL API directly. You need to exchange them for a temporary token which will expire periodically.

To do this, send a post to

var request = require("request"); 
var CLIENTID = "abc123";
var SECRET = "XYZ123"; // don't really write this in your code, keep in secure
var options = { 
  method: 'POST', 
  url: 'https://chainio.auth0.com/oauth/token', 
  headers: { 'content-type': 'application/json' }, 
  body: JSON.stringify({
    client_id: CLIENTID,
    client_secret: SECRET,
    audience: "https://portal-api.chain.io",
    grant_type: "client_credentials"
  })
}; 

request(options, function (error, response, body) { 
  if (error) throw new Error(error); 
  console.log(body); 
});

This will return a response like

{
  "access_token": "mytoken", 
  "token_type": "Bearer" 
}

Use the access_token in the next step.

Send your access token in your GraphQL requests

When you send a GraphQL request, you'll send your access token as a Bearer token like this:

var request = require("request");

var options = { 
  method: 'POST',
  url: 'https://portal-api.chain.io/graphql',
  headers: { 
    authorization: 'Bearer mytoken' 
  },
  body: JSON.stringify({
    query: "{ companies { company_name } }"
  })
};

request(options, function (error, response, body) {
if (error) throw new Error(error);

console.log(body);
});

More GraphQL Resources

You can learn more about GraphQL at https://graphql.org which includes both documentation as well as libraries for a range of programming languages.