Developer quickstart

Connect a test device and read its data with the Texture API

This quickstart is for developers building on the Texture API. You'll create a Texture Connect link with the API, connect a virtual device through it, and read the device back. You don't need real hardware.

If you work in the Texture dashboard instead, see Start here.

Before you begin#

You need a Texture account and organization, and the Admin or Operator role in that organization. Other roles can't create API keys or virtual devices. See Set up your Texture account.

Do this quickstart in your sandbox workspace. Use the workspace selector in the dashboard to switch to it. API keys, devices, and test data all belong to the workspace you create them in.

Step 1: Create an API key#

  1. In the dashboard, go to Developer → API Keys.
  2. Click Add API Key.
  3. Enter a Name, keep the Type as Server Key, and click Create API Key.
  4. Copy the key. You won't be able to see the full key again after you close the dialog.

Save the key in an environment variable for the rest of this guide:

export TEXTURE_API_KEY="<your-api-key>"

To learn about the other key types, see API keys.

Step 2: Create a virtual device#

Virtual devices behave like real devices from a manufacturer, so you can test the full connection flow.

  1. Go to Developer → Virtual Devices.
  2. Under Accounts, click Create Account.
  3. Enter a Name, an Email, and a Password, and set Account Type to OAuth. Note the email and password: you'll sign in with them in Step 4.
  4. Click Create.
  5. Under Devices, click Create Device, select the account you just created, choose a Device Type (for example, Battery), and click Create.
Use the OAuth account type

Only OAuth virtual accounts can connect through Texture Connect. A Default account can't sign in during the Connect flow.

Call the API to create a Connect session. Setting manufacturerFilters to texture limits the link to virtual devices, so your test customer goes straight to the right sign-in page.

curl -X POST https://api.texturehq.com/v1/connections \
  -H "Texture-Api-Key: $TEXTURE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://example.com/connected",
    "clientName": "My App",
    "manufacturerFilters": { "manufacturers": ["texture"] }
  }'

The response includes a linkUrl to send to your customer, and the customerId Texture created for them:

{
  "customerId": "cllh2buhk000008la0ln6cb80",
  "linkUrl": "https://connect.texturehq.com/link_e47b6d39dd3e6b3ab55969f55dc88ae6",
  "linkToken": "...",
  "linkSessionId": "...",
  "expiresAt": "..."
}

Step 4: Connect the device#

Open the linkUrl in your browser and go through the flow as your customer would:

  1. Click Continue, then enter a name, email, and address for your test customer, and click Continue.
  2. On the Texture sign-in step, click Sign In.
  3. Sign in with the virtual account's email and password from Step 2.
  4. On the success screen, click Continue.

Texture redirects you to your redirectUrl with two query parameters:

ParameterWhat it is
texture_scoped_keyA key that gives your application access to this customer's devices only. See Scoped keys.
texture_customer_idThe ID of the customer who connected

The redirect URL in this guide doesn't exist, so your browser shows an error page. Copy the parameters from the address bar.

Step 5: Read the device#

List the virtual devices in your workspace:

curl "https://api.texturehq.com/v1/devices?manufacturer=texture" \
  -H "Texture-Api-Key: $TEXTURE_API_KEY"

The response lists your connected device, with fields such as id, type, manufacturer, onlineStatus, and its current state. Results are paginated with page and perPage.

To get one device, use its id:

curl "https://api.texturehq.com/v1/devices/<device-id>" \
  -H "Texture-Api-Key: $TEXTURE_API_KEY"

You can also see the device, and the contact and site created for it, in the dashboard under Devices, Contacts, and Sites.

Next steps#