Quickstart

The Thing Identity public API lets your own systems work with your organization’s data without going through the dashboard. It is a machine-to-machine API: you authenticate with client credentials, not with a user account.

Create an API client

In the dashboard, go to Organization and open API. Create a client, give it a name you will recognise in the list later, and grant it the write:codes scope.You get a client ID (prefixed ti_client_) and a client secret. The secret is shown only at creation time, so copy it straight into your secret manager. If you lose it, delete the client and create a new one.

API clients require an active subscription on the Starter plan or above.

Exchange the credentials for an access token

curl -X POST https://api.thingidentity.com/oauth/token \
  -u "$TI_CLIENT_ID:$TI_CLIENT_SECRET" \
  -H "Accept: application/vnd.thingidentity.public.v1+json" \
  -d "grant_type=client_credentials"

{
  "access_token": "eyJ0eXAiOiJ0aS1hcGkrand0...",
  "token_type": "Bearer",
  "expires_in": 3600
}

The token is valid for one hour. See Authentication for the error responses and for how scopes work.

Generate a code

curl -X POST https://api.thingidentity.com/codes \
  -H "Authorization: Bearer $TI_ACCESS_TOKEN" \
  -H "Accept: application/vnd.thingidentity.public.v1+json" \
  -H "Content-Type: application/vnd.thingidentity.public.v1+json" \
  -d '{
    "codes": [
      {
        "reference": "product-label",
        "mode": "QR_GS1_DIGITAL_LINK_URI",
        "primaryKey": { "key": "01", "value": "09521234543213" },
        "ais": [],
        "extensionParameters": [],
        "digitalLinkStem": "https://gtin.at",
        "linkType": null,
        "context": null,
        "language": "en-us"
      }
    ]
  }'

{
  "codes": [
    {
      "reference": "product-label",
      "mode": "QR_GS1_DIGITAL_LINK_URI",
      "primaryKey": { "key": "01", "value": "09521234543213" },
      "barcodeText": "https://gtin.at/01/09521234543213",
      "hri": "(01)09521234543213"
    }
  ],
  "failures": []
}

barcodeText is the payload to hand to your 2D barcode renderer, hri is the human readable interpretation printed under the symbol. Full field reference in Generate codes.

The examples send Accept: application/vnd.thingidentity.public.v1+json to pin the API version. It is optional, application/json and a plain wildcard work as well, but pinning it means a future v2 cannot reshape your responses. See API conventions.

API conventions

Base URL, media types, error format and status codes.

Generate codes

Every field of POST /codes and what makes a definition valid.

Get Started

Guides

API Documentation

Endpoints

API conventions

Generate codes