Local API Token

Modern residential devices, such as ventilation units, airflow devices, and heat pumps, often provide local APIs for direct interaction. These APIs allow users to control devices locally via networks like WiFi or Ethernet. To ensure secure access, local APIs require authentication. This guide explains how you can create Local API Tokens within DRIVR, how the get transferred to your System and how to use them.

How Local API Tokens Work

1. A user generates a Local API Token via DRIVR.
2. The token is signed by DRIVR and contains encoded user credentials, roles, and access rights.
3. The device receives the Local API Token and JWK information securely via it's MQTT connection from DRIVR.
4. The user presents the token to a local device API, which verifies its authenticity using DRIVR’s public keys.
5. If the token is valid, the local device accepts the user’s identity and permissions.

MQTT Topics for Local API Tokens

For detailed information on retrieving Local API Tokens and JWKs, refer to the MQTT Documentation.

• Local API Token Information:
  Devices can retrieve local API token details from the following topic:
  drivr/v1/{slug}/authorization/localApiTokens/{systemUuid}
• JWKs for Token Validation:
  Devices can access the JWKs to validate user-provided tokens via this topic:
  drivr/v1/{slug}/jwks

Devices can securely operate locally even with limited internet connectivity. However, they must connect online periodically to retrieve the latest JWKs. Additionally, if a token is revoked, the device may remain unaware until it reconnects to update its token status.

Types of Local API Tokens

There are two types of Local API Tokens:

1. Short-Lived Tokens

• Expiration: These tokens have a defined expiration duration (e.g., 1 hour, 1 day).
• Extension: They can be extended before expiration.
• Use Case: Ideal for temporary access to local APIs.
• Automatic Deletion: Expired tokens are automatically deleted after their duration ends.

Example: Creating a Short-Lived Token

mutation {
  createLocalApiToken(
    systemUuid: "88113ca5-a499-458b-85d3-6285262b06e3"
    requestedDevice: "some-device"
    duration: "1D"
  ) {
    jwt
    uuid    
  }
}

{
  "data": {
    "createLocalApiToken": {
      "jwt": "CLOUD-eyJhUxMiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0MDE0lMWE4LTViNjEtNDczMS1hZWFmLTBiZDdhYjk4MjA1ZCIsImlhdCI6MTc0MzI0ODY1NCwibmJmIjoxNzQzMjQ4NjU0LCJleHAiOjE3NDMzMzUwNTQsIm5hbWUiOiJOZWV0YSIsInR5cGVuYW1lIjoiVV",
      "uuid": "40143687-a5a8-49f2-9019-e2e6d8ef7489"
    }
  }
}

2. Permanent Tokens

• No Expiration: These tokens do not expire unless manually revoked.
• Use Case: Suitable for third-party integrations (e.g., Home Assistant).
• Unique Name: Each token must have a unique name per user and system.
• Manual Deletion: These tokens are not automatically deleted, even if revoked.

Example: Creating a Permanent Token

mutation createPermanentLocalApiToken {
  createPermanentLocalApiToken(
    systemUuid:  "4449e1a8-5b61-4731-aeaf-0bd7ab98205d"
    name: "a-token-name"
  ) {
    jwt
    uuid    
  }
}

{
  "data": {
    "createLocalApiToken": {
      "jwt": "CLOUD-eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1NTBiZmUxNS03NDU3LTRlNjgtYTM3MS0yYWY1NmVmMmEwYzAiLCJzdWIiOiI5NGZkYTRmYi1kNTc0LTQ3MGItODJlMi0wZjRlYzJhMUCoxUmgkoomGVwy56E2CLQj6N20VtwptPxl86WU4CtUoxNNxSNaw_K7cVMhUMbff9dy_hl9DJnp9S7Wn7khjXd6A0wzOxbZKL9gMgPL5nI7w2RaQo",
      "uuid": "550bfe15-7457-4e68-a371-2af56ef2a0c0"
    }
  }
}

Note: The token value is only visible when it is created. Make sure to store it securely, as it cannot be retrieved later.

Managing Local API Tokens using DRIVR GraphQL

Listing Tokens:

Retrieve a list of all active tokens.

Example: Listing Your Tokens

query localApiTokens {
  localApiTokens {
    items{
    uuid
    systemUuid
    status
    }
  }
}

{
  "data": {
    "localApiTokens": {
      "items": [
        {
          "uuid": "7dc4095d-ae92-43ea-bf32-2462a1f1ed04",
          "systemUuid": "33c8ee43-ee78-4530-ae87-2ae96a97fdf3",
          "status": "ACTIVATED"
        },
        {
          "uuid": "3aca9b56-25ea-405d-91e0-54a1a587692c",
          "systemUuid": "33c8ee43-ee78-4530-ae87-2ae96a97fdf3",
          "status": "ACTIVATED"
        }
      ]
    }
  }
}

• Users can only see their own tokens.
• Users with EDIT rights on a system can see all tokens for that system.

Fetching a Specific Token

Retrieve details about a specific token using its UUID.

Example: Fetching a Token by UUID

query localApiToken{
  localApiToken(uuid: "645c2a69-3e59-4487-9189-fdbc6955f8da") {
    uuid
    systemUuid
    status
    
  }
}

{
  "data": {
    "localApiToken": {
      "uuid": "645c2a69-3e59-4487-9189-fdbc6955f8da",
      "systemUuid": "4449e1a8-5b61-4731-aeaf-0bd7ab98205d",
      "status": "ACTIVATED"
    }
  }
}

Extending a Token (Short-Lived Only)

Extend a short-lived token before it expires. The token will be extended by the same duration it was initially issued for.

Example: Extending a Token

mutation extendLocalApiToken{
  extendLocalApiToken(uuid: "ec3b35e0-37ee-42f2-b2e7-c70defa3eeb2") {
    uuid
    localApiToken {
      duration
      expiresAt
    }
    jwt
  }
}

{
  "data": {
    "extendLocalApiToken": {
      "uuid": "ec3b35e0-37ee-42f2-b2e7-c70defa3eeb2",
      "localApiToken": {
        "duration": "P1D",
        "expiresAt": "2025-02-18T18:24:42.832269"
      },
      "jwt": "CLOUD-eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

Note: You can only extend short-lived tokens before they expire.

Revoking a Token

Revoke a token to disable its access.

Example: Revoking a Token

mutation revokeLocalApiToken{
  revokeLocalApiToken(uuid: "ec3b35e0-37ee-42f2-b2e7-c70defa3eeb2") {
    uuid
    status
  }
}

{
  "data": {
    "revokeLocalApiToken": {
      "uuid": "ec3b35e0-37ee-42f2-b2e7-c70defa3eeb2",
      "status": "REVOKED"
    }
  }
}

Using Local API Tokens in MQTT

Publishing JWKs for Verification

• Devices need access to the latest JSON Web Keys (JWKs) to verify token authenticity.
• If a JWK changes, it is automatically re-published on the MQTT broker. Refer to MQTT topic: drivr/v1/{slug}/authorization/localApiTokens/{systemUuid} in Mqtt Docs.

Subscribing to Token Updates

• Devices can subscribe to token updates via MQTT to ensure they always reflect the latest permissions.
• Only non-expired, non-revoked tokens are published.
• If user roles change, token data is republished.

Topic for Token Updates:

drivr/v1/{slug}/authorization/localApiTokens/{system_uuid}

where {slug} is the domain slug and {system_uuid} is the system UUID.

Example Payload:

[
  {
    "uuid": "3aca9b56-25ea-405d-91e0-54a1a587692c",
    "createdAt": "2025-02-17T18:24:42.824834",
    "updatedAt": "2025-02-17T18:24:43.280174",
    "status": "ACTIVATED",
    "expiresAt": "2025-02-18T18:24:42.832269",
    "systemUuid": "33c8ee43-ee78-4530-ae87-2ae96a97fdf3",
    "roles": [
      {
        "uuid": "8d86661d-985d-4878-a8f5-69723acfa364",
        "name": "Domain Owner"
      }
    ],
    "token": "CLOUD-eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9..."
  }
]

Local API Tokens provide a secure way to control devices locally, even when offline.

By using short-lived or permanent tokens, you can manage access to local APIs effectively. Follow the examples provided to create, manage, and use tokens in your applications.