Getting started

This page takes you from a new CoCoCo tenant to your first API calls.

Your tenant

Each customer works in a tenant: your own data, users and configuration, reached at your tenant's host name (for example https://<your-tenant-host>). CoCoCo sets up the tenant and gives people access to it. You sign in through CoCoCo's central sign-in service: signing in on your tenant host sends you there and back, and the same login works across CoCoCo services.

Once you are signed in, the console gives developers:

• GraphQL Playground (/#/graphql-playground): run queries and mutations as yourself.
• API Docs (/#/docs): the schema reference, with guides on authentication, pagination and errors.
• Lua Playground (/#/lua-playground): run Lua scripts and see their output and logs.

Create an API token

Programs call the API with a bearer token.

• For an integration, create a service account: open Service accounts, create one, attach an IAM policy with only the permissions the integration needs, then create a token on the service account's page. Service accounts can't sign in, and the integration keeps working when the person who set it up leaves.
• For your own scripts and experiments, create a personal token from the user menu → API Tokens. It carries all of your permissions, so don't use it in long-running deployments.

A token is shown once, when you create it. Store it as a secret.

Make your first request

Every API call is a POST to /graphql on your tenant host, with the token in the Authorization header:

curl https://<your-tenant-host>/graphql \
  -H "Authorization: Bearer $COCOCO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ ping }"}'

A reachable endpoint answers {"data":{"ping":"pong"}}. ping needs no permissions, so use the next query to check that your token works.

Read some data

Lists are paginated connections. This returns the first five jobs:

query FirstJobs {
  listJobs(first: 5) {
    totalCount
    edges {
      node {
        id
        jobNumber
        name
        status
        dueAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Core patterns covers pagination, filtering, sorting and errors.

Create a job

Mutations return the changed record and a list of field errors:

mutation CreateJob {
  createJob(input: { name: "Brochure A4", quantity: 500 }) {
    job {
      id
      jobNumber
      status
    }
    errors {
      path
      message
    }
  }
}

An empty errors list means the job was created. The token needs the job:write permission.

React to what happens

Mutations that create, update or delete a record publish an event named <resource>.<verb>, such as job.created or order.updated. To act on one, create a workflow with an event trigger for that topic, and add a Lua script step where you need custom logic.

Connect a machine

Devices can send metrics to CoCoCo over MQTT with a client certificate; see MQTT getting started.

Next steps

• API overview
• Custom apps: build your own screens inside the console.
• API reference