v3.19.1

Getting Started Devices Gateways Integrations Reference
Get The Things Stack

Reference

    Overview
  • Adaptive Data Rate
  • API
    • Authentication
    • Fields and Field Masks
    • Application APIs
    • Application Package APIs
    • Application Pub/Sub APIs
    • Application Server APIs
    • Application Webhook APIs
    • Client APIs
    • End Device APIs
    • Events API
    • Gateway APIs
    • Gateway Server APIs
    • Gateway Server MQTT
    • Network Server APIs
    • Organization APIs
    • Storage Integration API
    • Tenant APIs
    • User APIs
  • Application Packages
  • Billing with Stripe
  • Command-Line Interface
  • Components
  • Configuration
  • Data Formats
  • Data Retention and Privacy
  • Email Templates
  • Federated Authentication
  • Frequency Plans
  • Gateway RTT
  • Glossary
  • ID and EUI Constraints
  • Last Activity
  • LoRa Basics Station Implementation Guide
  • LoRaWAN Backend Interfaces Interoperability
  • LoRaWAN Specification and Regional Parameters
  • Networking
  • Packet Broker Routing
  • Packet Forwarders
  • Purging Entities
  • Rate Limiting
  • Resource Limiting
  • Root Certificates
  • Telemetry
  • Tenant Management
  • Web UI Branding

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.GetRegistryTotals
Request type GetTenantRegistryTotalsRequest
Response type TenantRegistryTotals
HTTP bindings

GET /api/v3/tenants/{tenant_ids.tenant_id}/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}

Messages

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 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 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": {},
  "ns": {},
  "js": {},
}

Fields:

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

Identity Server configuration.

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

JoinServer

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.IdentityServer

Show object example
{
  "user_registration": {},
  "profile_picture": {},
  "end_device_picture": {},
  "user_rights": {},
  "admin_rights": {},
  "user_login": {},
}

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

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.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

Message Configuration.Cluster.NetworkServer

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

Fields:

Field dev_addr_prefixes
Type repeated bytes
Description
Field deduplication_window
Type google.protobuf. Duration
Field cooldown_window
Type google.protobuf. Duration

Message EntityCounting

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

Fields:

Field end_devices
Type EntityCounting.EntityCountingType

Enums

Enum EntityCounting.EntityCountingType

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

On this page

  • Authentication
  • The TenantRegistry service
  • Messages
  • Enums

The Things Stack

Getting Started

Devices

Gateways

Integrations

Reference

Contributing

GitHub

Forum

About Us

The Things Network

The Things Industries

About this page

Last changed by Nejra Selimović on 22 Sep 2021.
doc: Add v3.15.0 release docs (#572)

Edit on Github