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}`

The `EntityRegistrySearch` service

Method	`EntityRegistrySearch.SearchTenants`
Request type	`SearchTenantsRequest`
Response type	`Tenants`
HTTP bindings	`GET` `/api/v3/search/tenants`

Messages

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

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`

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

Field	`tenant_id`
Type	`string`
Description	`max_len`: `36` `pattern`: `^[a-z0-9](?:[-]?[a-z0-9]){2,}$`

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

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	Join Server

Field	`noc`
Type	`Configuration.Cluster.NetworkOperationsCenter`
Description	Network Operations Center

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

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

Fields:

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 →

Tenant APIs

Authentication

The TenantRegistry service

The EntityRegistrySearch service

Messages

Message Configuration.Cluster.IdentityServer.ApplicationLimits

Message Configuration.Cluster.IdentityServer.OrganizationLimits

Message Configuration.Cluster.IdentityServer.UserLimits

Message Tenant

Message TenantIdentifiers

Message Tenants

Message CreateTenantRequest

Message GetTenantRequest

Message GetTenantRegistryTotalsRequest

Message TenantRegistryTotals

Message ListTenantsRequest

Message UpdateTenantRequest

Message Configuration

Message Billing

Message BillingIdentifiers

Message Configuration.Cluster

Message Configuration.PacketBroker

Message Billing.Stripe

Message Billing.AWSSaaSMarketplace

Message Configuration.UI

Message Configuration.Cluster.IdentityServer

Message Configuration.Cluster.IdentityServer.UserRegistration

Message Configuration.Cluster.IdentityServer.UserRegistration.Invitation

Message Configuration.Cluster.IdentityServer.UserRegistration.ContactInfoValidation

Message Configuration.Cluster.IdentityServer.UserRegistration.AdminApproval

Message Configuration.Cluster.IdentityServer.UserRegistration.PasswordRequirements

Message Configuration.Cluster.IdentityServer.ProfilePicture

Message Configuration.Cluster.IdentityServer.UserLogin

Message Configuration.Cluster.IdentityServer.Email

Message Configuration.Cluster.IdentityServer.Email.Network

Message Configuration.Cluster.IdentityServer.EndDevicePicture

Message Configuration.Cluster.IdentityServer.UserRights

Message Configuration.Cluster.IdentityServer.AdminRights

Message Configuration.Cluster.JoinServer

Message Configuration.Cluster.NetworkServer

Message Configuration.Cluster.NetworkOperationsCenter

Message Configuration.Cluster.NetworkOperationsCenter.Access

Message EntityCounting

Message SearchTenantsRequest

Enums

Enum EntityCounting.EntityCountingType

The `TenantRegistry` service

The `EntityRegistrySearch` service

Message `Configuration.Cluster.IdentityServer.ApplicationLimits`

Message `Configuration.Cluster.IdentityServer.OrganizationLimits`

Message `Configuration.Cluster.IdentityServer.UserLimits`

Message `Tenant`

Message `TenantIdentifiers`

Message `Tenants`

Message `CreateTenantRequest`

Message `GetTenantRequest`

Message `GetTenantRegistryTotalsRequest`

Message `TenantRegistryTotals`

Message `ListTenantsRequest`

Message `UpdateTenantRequest`

Message `Configuration`

Message `Billing`

Message `BillingIdentifiers`

Message `Configuration.Cluster`

Message `Configuration.PacketBroker`

Message `Billing.Stripe`

Message `Billing.AWSSaaSMarketplace`

Message `Configuration.UI`

Message `Configuration.Cluster.IdentityServer`

Message `Configuration.Cluster.IdentityServer.UserRegistration`

Message `Configuration.Cluster.IdentityServer.UserRegistration.Invitation`

Message `Configuration.Cluster.IdentityServer.UserRegistration.ContactInfoValidation`

Message `Configuration.Cluster.IdentityServer.UserRegistration.AdminApproval`

Message `Configuration.Cluster.IdentityServer.UserRegistration.PasswordRequirements`

Message `Configuration.Cluster.IdentityServer.ProfilePicture`

Message `Configuration.Cluster.IdentityServer.UserLogin`

Message `Configuration.Cluster.IdentityServer.Email`

Message `Configuration.Cluster.IdentityServer.Email.Network`

Message `Configuration.Cluster.IdentityServer.EndDevicePicture`

Message `Configuration.Cluster.IdentityServer.UserRights`

Message `Configuration.Cluster.IdentityServer.AdminRights`

Message `Configuration.Cluster.JoinServer`

Message `Configuration.Cluster.NetworkServer`

Message `Configuration.Cluster.NetworkOperationsCenter`

Message `Configuration.Cluster.NetworkOperationsCenter.Access`

Message `EntityCounting`

Message `SearchTenantsRequest`

Enum `EntityCounting.EntityCountingType`