> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thingidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create an API client, exchange it for a token and start using the API.

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.

<Steps>
  <Step title="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.

    <Note>
      API clients require an active subscription on the Starter plan or above.
    </Note>
  </Step>

  <Step title="Exchange the credentials for an access token">
    ```bash theme={null}
    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"
    ```

    ```json theme={null}
    {
      "access_token": "eyJ0eXAiOiJ0aS1hcGkrand0...",
      "token_type": "Bearer",
      "expires_in": 3600
    }
    ```

    The token is valid for one hour. See [Authentication](/guides/authentication) for the
    error responses and for how scopes work.
  </Step>

  <Step title="Generate a code">
    ```bash theme={null}
    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"
          }
        ]
      }'
    ```

    ```json theme={null}
    {
      "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](/api-reference/endpoints/generate-codes).
  </Step>
</Steps>

<Tip>
  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-reference/introduction#media-types).
</Tip>

<CardGroup cols={2}>
  <Card title="API conventions" icon="book" href="/api-reference/introduction">
    Base URL, media types, error format and status codes.
  </Card>

  <Card title="Generate codes" icon="qrcode" href="/api-reference/codes">
    Every field of `POST /codes` and what makes a definition valid.
  </Card>
</CardGroup>