Skip to main content

Authentication

Core API authentication is via an API key. To create an API key you'll first need to create a Machine User. After you have an API key you'll need to set it as a header:

Authorization: Bearer plainApiKey_xxx

Data model​

Machine User Data Model

  • Machine User: A user-like persona that models one of your backend systems.
  • API Key: A secret that should be kept secure. A machine user can have multiple API keys, therefore making key rotation simple. An API key can't be updated only deleted and recreated.
  • Permission: Fine grained permissions that are required for each API call. See API reference for which API calls require which permissions.

This data model allows you to apply security best practice and give each of your backend systems an API key with the least privileges while still maintaining a logical grouping and consistent experience via the Machine User.

For example:

  • Machine user:
    • Name: Order workflow
    • Public name: Acme Orders (this is the name that will be visible to customers)
  • API Keys:
    • Order created microservice with timeline:create permission to create custom timeline entries.
    • Order dispatch microservice with timeline:edit permission to update the custom timeline entry after the order has been dispatched.

Creating a machine user​

You can create a Machine User under Settings -> Developer -> Machine Users:

Creating a Machine User

Creating an API key​

You can create an API key for a machine user:

Creating a Machine User