Getting Started Concepts The Things Stack Cloud The Things Stack Enterprise Integrations API Hardware
Get The Things Stack

API

    Overview
  • Concepts
  • Reference
    • HTTP(REST)
    • gRPC
      • Application APIs
      • Application Package APIs
      • Application Pub/Sub APIs
      • Application Server APIs
      • Application Webhook APIs
      • Client APIs
      • Crypto Operations APIs
      • End Device APIs
      • Events API
      • Gateway APIs
      • Gateway Server APIs
      • Identity Server APIs
      • Join Server APIs
      • Network Operations Center APIs
      • Network Server APIs
      • Organization APIs
      • Packet Broker APIs
      • Storage Integration API
      • Tenant APIs
      • User APIs

Tenant APIs

List of Tenant APIs.

Authentication

Unlike the other services, the tenant services do not accept API keys or OAuth access tokens. Instead, authentication is done with a “tenant admin key” that is configured in the Identity Server

  • Usage with HTTP Authorization Header: TenantAdminKey XXXXX
  • Usage with gRPC call credentials (in the authorization header): TenantAdminKey XXXXX

The TenantRegistry service

Method TenantRegistry.Create
Request type CreateTenantRequest
Response type Tenant
HTTP bindings

POST /api/v3/tenants

Method TenantRegistry.Get
Request type GetTenantRequest
Response type Tenant
HTTP bindings

GET /api/v3/tenants/{tenant_ids.tenant_id}

Method TenantRegistry.GetIdentifiersForEndDeviceEUIs
Request type GetTenantIdentifiersForEndDeviceEUIsRequest
Response type TenantIdentifiers
HTTP bindings
Method TenantRegistry.GetIdentifiersForGatewayEUI
Request type GetTenantIdentifiersForGatewayEUIRequest
Response type TenantIdentifiers
HTTP bindings
Method TenantRegistry.GetIdentifiersForBillingIdentifiers
Request type GetTenantIdentifiersForBillingIdentifiersRequest
Response type TenantIdentifiers
HTTP bindings
Method TenantRegistry.GetRegistryTotals
Request type GetTenantRegistryTotalsRequest
Response type TenantRegistryTotals
HTTP bindings

GET /api/v3/tenants/{tenant_ids.tenant_id}/registry-totals

Method TenantRegistry.BatchGetRegistryTotals
Request type BatchGetTenantRegistryTotalsRequest
Response type BatchGetTenantRegistryTotalsResponse
HTTP bindings

POST /api/v3/tenants/registry-totals

Method TenantRegistry.List
Request type ListTenantsRequest
Response type Tenants
HTTP bindings

GET /api/v3/tenants

Method TenantRegistry.Update
Request type UpdateTenantRequest
Response type Tenant
HTTP bindings

PUT /api/v3/tenants/{tenant.ids.tenant_id}

Method TenantRegistry.Delete
Request type TenantIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/tenants/{tenant_id}

The EntityRegistrySearch service

Method EntityRegistrySearch.SearchTenants
Request type SearchTenantsRequest
Response type Tenants
HTTP bindings

GET /api/v3/search/tenants

The Tbs service

Method Tbs.Report
Request type MeteringData
Response type google.protobuf.Empty
HTTP bindings

POST /api/v3/tbs/report

Messages

Message BatchGetTenantRegistryTotalsRequest

Show object example
{
  "tenant_ids": [],
  "field_mask": {},
}

Fields:

Field tenant_ids
Type repeated TenantIdentifiers
Description
Field field_mask
Type google.protobuf. FieldMask

Message Configuration.Cluster.AlertRoutingServer

Show object example
{
  "routing": {},
}

Fields:

Field routing
Type Configuration.Cluster.AlertRoutingServer.Routing

Message Configuration.Cluster.AlertRoutingServer.Routing

Show object example
{
  "enabled": null,
}

Fields:

Field enabled
Type google.protobuf. BoolValue

Message Configuration.Cluster.IdentityServer.ApplicationLimits

Show object example
{
  "end_devices": null,
}

Fields:

Field end_devices
Type google.protobuf. UInt64Value

Message Configuration.Cluster.IdentityServer.OrganizationLimits

Show object example
{
  "applications": null,
  "clients": null,
  "gateways": null,
}

Fields:

Field applications
Type google.protobuf. UInt64Value
Field clients
Type google.protobuf. UInt64Value
Field gateways
Type google.protobuf. UInt64Value

Message Configuration.Cluster.IdentityServer.UserLimits

Show object example
{
  "applications": null,
  "clients": null,
  "gateways": null,
  "organizations": null,
}

Fields:

Field applications
Type google.protobuf. UInt64Value
Field clients
Type google.protobuf. UInt64Value
Field gateways
Type google.protobuf. UInt64Value
Field organizations
Type google.protobuf. UInt64Value

Message Tenant

Tenant is the message that defines a Tenant in the network.

Show object example
{
  "ids": {},
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "name": "",
  "description": "",
  "attributes": {},
  "contact_info": [],
  "max_applications": null,
  "max_clients": null,
  "max_end_devices": null,
  "max_gateways": null,
  "max_organizations": null,
  "max_users": null,
  "state": "STATE_REQUESTED",
  "state_description": "",
  "capabilities": {},
  "configuration": {},
  "billing": {},
  "billing_identifiers": {},
}

Fields:

Field ids
Type TenantIdentifiers
Description

required

Field created_at
Type google.protobuf. Timestamp
Field updated_at
Type google.protobuf. Timestamp
Field name
Type string
Description

max_len: 50

Field description
Type string
Description

max_len: 2000

Field attributes
Type map of string to string
Field contact_info
Type repeated ttn.lorawan.v3. ContactInfo
Description
Field max_applications
Type google.protobuf. UInt64Value
Description

If set, restricts the maximum number of applications that can be created.

Field max_clients
Type google.protobuf. UInt64Value
Description

If set, restricts the maximum number of clients that can be created.

Field max_end_devices
Type google.protobuf. UInt64Value
Description

If set, restricts the maximum number of end_devices that can be created.

Field max_gateways
Type google.protobuf. UInt64Value
Description

If set, restricts the maximum number of gateways that can be created.

Field max_organizations
Type google.protobuf. UInt64Value
Description

If set, restricts the maximum number of organizations that can be created.

Field max_users
Type google.protobuf. UInt64Value
Description

If set, restricts the maximum number of users that can be created.

Field state
Type ttn.lorawan.v3. State
Description

The reviewing state of the tenant. This field can only be modified by tenant admins. If state_description is not updated when updating state, state_description is cleared.

defined_only

Field state_description
Type string
Description

A description for the state field. This field can only be modified by admins, and should typically only be updated when also updating state.

max_len: 128

Field capabilities
Type google.protobuf. Struct
Field configuration
Type Configuration
Field billing
Type Billing
Field billing_identifiers
Type BillingIdentifiers

Message TenantIdentifiers

Show object example
{
  "tenant_id": "",
}

Fields:

Field tenant_id
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

Message Tenants

Show object example
{
  "tenants": [],
}

Fields:

Field tenants
Type repeated Tenant
Description

Message CreateTenantRequest

Show object example
{
  "tenant": {},
  "initial_user": {},
}

Fields:

Field tenant
Type Tenant
Description

required

Field initial_user
Type ttn.lorawan.v3. User

Message GetTenantRequest

Show object example
{
  "tenant_ids": {},
  "field_mask": {},
}

Fields:

Field tenant_ids
Type TenantIdentifiers
Description

required

Field field_mask
Type google.protobuf. FieldMask

Message GetTenantIdentifiersForEndDeviceEUIsRequest

Show object example
{
  "join_eui": "",
  "dev_eui": "",
}

Fields:

Field join_eui
Type bytes
Description

ignore_empty

len: 8

Field dev_eui
Type bytes
Description

ignore_empty

len: 8

Message GetTenantIdentifiersForGatewayEUIRequest

Show object example
{
  "eui": "",
}

Fields:

Field eui
Type bytes
Description

ignore_empty

len: 8

Message GetTenantIdentifiersForBillingIdentifiersRequest

Show object example
{
  "ids": {},
}

Fields:

Field ids
Type BillingIdentifiers
Description

required

Message GetTenantRegistryTotalsRequest

Show object example
{
  "tenant_ids": {},
  "field_mask": {},
}

Fields:

Field tenant_ids
Type TenantIdentifiers
Field field_mask
Type google.protobuf. FieldMask

Message TenantRegistryTotals

Show object example
{
  "applications": 0,
  "clients": 0,
  "end_devices": 0,
  "activated_end_devices": 0,
  "gateways": 0,
  "organizations": 0,
  "users": 0,
}

Fields:

Field applications
Type uint64
Field clients
Type uint64
Field end_devices
Type uint64
Field activated_end_devices
Type uint64
Field gateways
Type uint64
Field organizations
Type uint64
Field users
Type uint64

Message ListTenantsRequest

Show object example
{
  "field_mask": {},
  "order": "",
  "limit": 0,
  "page": 0,
}

Fields:

Field field_mask
Type google.protobuf. FieldMask
Field order
Type string
Description

Order the results by this field path (must be present in the field mask). Default ordering is by ID. Prepend with a minus (-) to reverse the order.

in: [ tenant_id -tenant_id name -name created_at -created_at]

Field limit
Type uint32
Description

Limit the number of results per page.

lte: 1000

Field page
Type uint32
Description

Page number for pagination. 0 is interpreted as 1.

Message MeteringData

Show object example
{
  "tenants": [],
}

Fields:

Field tenants
Type repeated MeteringData.TenantMeteringData
Description

Message MeteringData.TenantMeteringData

Show object example
{
  "tenant_id": {},
  "totals": {},
}

Fields:

Field tenant_id
Type TenantIdentifiers
Field totals
Type TenantRegistryTotals

Message UpdateTenantRequest

Show object example
{
  "tenant": {},
  "field_mask": {},
}

Fields:

Field tenant
Type Tenant
Description

required

Field field_mask
Type google.protobuf. FieldMask

Message Configuration

Show object example
{
  "default_cluster": {},
  "clusters": {},
  "pb": {},
}

Fields:

Field default_cluster
Type Configuration.Cluster
Description

Default cluster configuration.

Field clusters
Type map of string to Configuration.Cluster
Description

Configuration per cluster (by ID).

Field pb
Type Configuration.PacketBroker
Description

Packet Broker configuration.

Message Billing

Restrictions:
  • Only one of stripe, aws_saas_marketplace can be set.
Show object example
{
  "counting": {},
  "stripe": {},
  "aws_saas_marketplace": {},
}

Fields:

Field counting
Type EntityCounting
Field stripe
Type Billing.Stripe
Field aws_saas_marketplace
Type Billing.AWSSaaSMarketplace

Message BillingIdentifiers

Show object example
{
  "billing_id": "",
}

Fields:

Field billing_id
Type string
Description

max_len: 250

Message Configuration.Cluster

Show object example
{
  "ui": {},
  "is": {},
  "gs": {},
  "ns": {},
  "as": {},
  "js": {},
  "noc": {},
  "ars": {},
}

Fields:

Field ui
Type Configuration.UI
Field is
Type Configuration.Cluster.IdentityServer
Description

Identity Server configuration.

Field gs
Type Configuration.Cluster.GatewayServer
Description

Gateway Server configuration.

Field ns
Type Configuration.Cluster.NetworkServer
Field as
Type Configuration.Cluster.ApplicationServer
Field js
Type Configuration.Cluster.JoinServer
Description

Join Server configuration.

Field noc
Type Configuration.Cluster.NetworkOperationsCenter
Description

Network Operations Center configuration.

Field ars
Type Configuration.Cluster.AlertRoutingServer
Description

Alert Routing Server configuration.

Message Configuration.PacketBroker

Show object example
{
  "listed": false,
}

Fields:

Field listed
Type bool
Description

Indicates whether the Home Network is publicly listed.

Message Billing.Stripe

Show object example
{
  "customer_id": "",
  "plan_id": "",
  "subscription_id": "",
  "subscription_item_id": "",
}

Fields:

Field customer_id
Type string
Description

min_len: 1

Field plan_id
Type string
Description

min_len: 1

Field subscription_id
Type string
Description

min_len: 1

Field subscription_item_id
Type string
Description

min_len: 1

Message Billing.AWSSaaSMarketplace

Show object example
{
  "customer_identifier": "",
  "product_code": "",
}

Fields:

Field customer_identifier
Type string
Description

min_len: 1

Field product_code
Type string
Description

min_len: 1

Message Configuration.UI

Show object example
{
  "branding_base_url": "",
}

Fields:

Field branding_base_url
Type string

Message Configuration.Cluster.ApplicationServer

Show object example
{
  "webhooks": {},
}

Fields:

Field webhooks
Type Configuration.Cluster.ApplicationServer.Webhooks

Message Configuration.Cluster.ApplicationServer.Webhooks

Show object example
{
  "queue": {},
}

Fields:

Field queue
Type Configuration.Cluster.ApplicationServer.Webhooks.Queue

Message Configuration.Cluster.ApplicationServer.Webhooks.Queue

Show object example
{
  "enabled": null,
}

Fields:

Field enabled
Type google.protobuf. BoolValue

Message Configuration.Cluster.GatewayServer

Show object example
{
  "mtls_authentication": {},
}

Fields:

Field mtls_authentication
Type Configuration.Cluster.GatewayServer.MTLSAuthentication

Message Configuration.Cluster.GatewayServer.MTLSAuthentication

Show object example
{
  "client_ca_pool": "",
}

Fields:

Field client_ca_pool
Type bytes
Description

PEM encoded pool of X.509 root certificates to trust for verifying the presented TLS client certificate.

Message Configuration.Cluster.IdentityServer

Show object example
{
  "user_registration": {},
  "profile_picture": {},
  "end_device_picture": {},
  "user_rights": {},
  "admin_rights": {},
  "user_login": {},
  "email": {},
  "application_limits": {},
  "organization_limits": {},
  "user_limits": {},
}

Fields:

Field user_registration
Type Configuration.Cluster.IdentityServer.UserRegistration
Field profile_picture
Type Configuration.Cluster.IdentityServer.ProfilePicture
Field end_device_picture
Type Configuration.Cluster.IdentityServer.EndDevicePicture
Field user_rights
Type Configuration.Cluster.IdentityServer.UserRights
Field admin_rights
Type Configuration.Cluster.IdentityServer.AdminRights
Field user_login
Type Configuration.Cluster.IdentityServer.UserLogin
Field email
Type Configuration.Cluster.IdentityServer.Email
Field application_limits
Type Configuration.Cluster.IdentityServer.ApplicationLimits
Description

The default limits set on newly created applications. Note that these limits do not override the limits of the tenant or the license.

Field organization_limits
Type Configuration.Cluster.IdentityServer.OrganizationLimits
Description

The default limits set on newly created organizations. Note that these limits do not override the limits of the tenant or the license.

Field user_limits
Type Configuration.Cluster.IdentityServer.UserLimits
Description

The default limits set on newly created users. Note that these limits do not override the limits of the tenant or the license.

Message Configuration.Cluster.IdentityServer.UserRegistration

Show object example
{
  "invitation": {},
  "contact_info_validation": {},
  "admin_approval": {},
  "password_requirements": {},
  "enabled": null,
}

Fields:

Field invitation
Type Configuration.Cluster.IdentityServer.UserRegistration.Invitation
Field contact_info_validation
Type Configuration.Cluster.IdentityServer.UserRegistration.ContactInfoValidation
Field admin_approval
Type Configuration.Cluster.IdentityServer.UserRegistration.AdminApproval
Field password_requirements
Type Configuration.Cluster.IdentityServer.UserRegistration.PasswordRequirements
Field enabled
Type google.protobuf. BoolValue

Message Configuration.Cluster.IdentityServer.UserRegistration.Invitation

Show object example
{
  "required": null,
  "token_ttl": "0s",
}

Fields:

Field required
Type google.protobuf. BoolValue
Field token_ttl
Type google.protobuf. Duration

Message Configuration.Cluster.IdentityServer.UserRegistration.ContactInfoValidation

Show object example
{
  "required": null,
}

Fields:

Field required
Type google.protobuf. BoolValue

Message Configuration.Cluster.IdentityServer.UserRegistration.AdminApproval

Show object example
{
  "required": null,
}

Fields:

Field required
Type google.protobuf. BoolValue

Message Configuration.Cluster.IdentityServer.UserRegistration.PasswordRequirements

Show object example
{
  "min_length": null,
  "max_length": null,
  "min_uppercase": null,
  "min_digits": null,
  "min_special": null,
}

Fields:

Field min_length
Type google.protobuf. UInt32Value
Field max_length
Type google.protobuf. UInt32Value
Field min_uppercase
Type google.protobuf. UInt32Value
Field min_digits
Type google.protobuf. UInt32Value
Field min_special
Type google.protobuf. UInt32Value

Message Configuration.Cluster.IdentityServer.ProfilePicture

Show object example
{
  "disable_upload": null,
  "use_gravatar": null,
}

Fields:

Field disable_upload
Type google.protobuf. BoolValue
Field use_gravatar
Type google.protobuf. BoolValue

Message Configuration.Cluster.IdentityServer.UserLogin

Show object example
{
  "disable_credentials_login": null,
}

Fields:

Field disable_credentials_login
Type google.protobuf. BoolValue

Message Configuration.Cluster.IdentityServer.Email

Show object example
{
  "network": {},
}

Fields:

Field network
Type Configuration.Cluster.IdentityServer.Email.Network

Message Configuration.Cluster.IdentityServer.Email.Network

Show object example
{
  "branding_base_url": "",
}

Fields:

Field branding_base_url
Type string

Message Configuration.Cluster.IdentityServer.EndDevicePicture

Show object example
{
  "disable_upload": null,
}

Fields:

Field disable_upload
Type google.protobuf. BoolValue

Message Configuration.Cluster.IdentityServer.UserRights

Show object example
{
  "create_applications": null,
  "create_clients": null,
  "create_gateways": null,
  "create_organizations": null,
  "update_primary_email_address": null,
  "update_name": null,
}

Fields:

Field create_applications
Type google.protobuf. BoolValue
Field create_clients
Type google.protobuf. BoolValue
Field create_gateways
Type google.protobuf. BoolValue
Field create_organizations
Type google.protobuf. BoolValue
Field update_primary_email_address
Type google.protobuf. BoolValue
Field update_name
Type google.protobuf. BoolValue

Message Configuration.Cluster.IdentityServer.AdminRights

Show object example
{
  "all": null,
}

Fields:

Field all
Type google.protobuf. BoolValue

Message Configuration.Cluster.JoinServer

Show object example
{
  "join_eui_prefixes": [],
}

Fields:

Field join_eui_prefixes
Type repeated bytes
Description

len: 9

Message Configuration.Cluster.NetworkServer

Show object example
{
  "net_id": "",
  "ns_id": "",
  "dev_addr_prefixes": [],
  "deduplication_window": "0s",
  "cooldown_window": "0s",
}

Fields:

Field net_id
Type bytes
Description

ignore_empty

len: 3

Field ns_id
Type bytes
Description

ignore_empty

len: 8

Field dev_addr_prefixes
Type repeated bytes
Description

len: 5

Field deduplication_window
Type google.protobuf. Duration
Field cooldown_window
Type google.protobuf. Duration

Message Configuration.Cluster.NetworkOperationsCenter

Show object example
{
  "access": {},
}

Fields:

Field access
Type Configuration.Cluster.NetworkOperationsCenter.Access

Message Configuration.Cluster.NetworkOperationsCenter.Access

Show object example
{
  "extended": null,
}

Fields:

Field extended
Type google.protobuf. BoolValue

Message EntityCounting

Show object example
{
  "end_devices": "ALL",
}

Fields:

Field end_devices
Type EntityCounting.EntityCountingType

Message SearchTenantsRequest

This message is used for finding tenants in the EntityRegistrySearch service.

Show object example
{
  "id_contains": "",
  "name_contains": "",
  "description_contains": "",
  "attributes_contain": {},
  "state": [],
  "field_mask": {},
  "order": "",
  "limit": 0,
  "page": 0,
  "deleted": false,
}

Fields:

Field id_contains
Type string
Description

Find tenants where the ID contains this substring.

max_len: 50

Field name_contains
Type string
Description

Find tenants where the name contains this substring.

max_len: 50

Field description_contains
Type string
Description

Find tenants where the description contains this substring.

max_len: 50

Field attributes_contain
Type map of string to string
Description

Find tenants where the given attributes contain these substrings.

max_pairs: 10

max_len (key): 36

pattern (key): ^[a-z0-9](?:[-]?[a-z0-9]){2,}$

max_len (value): 50

Field state
Type repeated ttn.lorawan.v3. State
Description

Find tenants where the state is any of these states.

Field field_mask
Type google.protobuf. FieldMask
Field order
Type string
Description

Order the results by this field path (must be present in the field mask). Default ordering is by ID. Prepend with a minus (-) to reverse the order.

in: [ tenant_id -tenant_id name -name created_at -created_at]

Field limit
Type uint32
Description

Limit the number of results per page.

lte: 1000

Field page
Type uint32
Description

Page number for pagination. 0 is interpreted as 1.

Field deleted
Type bool
Description

Only return recently deleted tenants.

Enums

Enum EntityCounting.EntityCountingType

Name Value Description
ALL 0
ONLY_ACTIVATED 1
← Storage Integration API User APIs →

On this page

  • Authentication
  • The TenantRegistry service
  • The EntityRegistrySearch service
  • The Tbs service
  • Messages
  • Enums

Sections

Getting Started

Concepts

The Things Stack Cloud

The Things Stack Enterprise

Integrations

API

Hardware

Sitemap

View our Sitemap

Contributing

GitHub

About Us

The Things Industries