Gateway APIs

List of LoRaWAN® Gateway APIs.

The GatewayRegistry service

Method GatewayRegistry.Create
Description Create a new gateway. This also sets the given organization or user as first collaborator with all possible rights.
Request type CreateGatewayRequest
Response type Gateway
HTTP bindings

POST /api/v3/users/{collaborator.user_ids.user_id}/gateways

POST /api/v3/organizations/{collaborator.organization_ids.organization_id}/gateways
Method GatewayRegistry.Get
Description Get the gateway with the given identifiers, selecting the fields specified in the field mask. More or less fields may be returned, depending on the rights of the caller.
Request type GetGatewayRequest
Response type Gateway
HTTP bindings

GET /api/v3/gateways/{gateway_ids.gateway_id}
Method GatewayRegistry.List
Description List gateways where the given user or organization is a direct collaborator. If no user or organization is given, this returns the gateways the caller has access to. Similar to Get, this selects the fields given by the field mask. More or less fields may be returned, depending on the rights of the caller.
Request type ListGatewaysRequest
Response type Gateways
HTTP bindings

GET /api/v3/gateways

GET /api/v3/users/{collaborator.user_ids.user_id}/gateways

GET /api/v3/organizations/{collaborator.organization_ids.organization_id}/gateways

POST /api/v3/gateways/filter
Method GatewayRegistry.Update
Description Update the gateway, changing the fields specified by the field mask to the provided values.
Request type UpdateGatewayRequest
Response type Gateway
HTTP bindings

PUT /api/v3/gateways/{gateway.ids.gateway_id}
Method GatewayRegistry.Delete
Description Delete the gateway. This may not release the gateway ID for reuse, but it does release the EUI.
Request type GatewayIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/gateways/{gateway_id}
Method GatewayRegistry.Restore
Description

Restore a recently deleted gateway. This does not restore the EUI, as that was released when deleting the gateway.

Deployment configuration may specify if, and for how long after deletion, entities can be restored.
Request type GatewayIdentifiers
Response type google.protobuf.Empty
HTTP bindings

POST /api/v3/gateways/{gateway_id}/restore
Method GatewayRegistry.Purge
Description Purge the gateway. This will release both gateway ID and EUI for reuse. The gateway owner is responsible for clearing data from any (external) integrations that may store and expose data by gateway ID.
Request type GatewayIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/gateways/{gateway_id}/purge
Method GatewayRegistry.GetIdentifiersForEUI
Description Get the identifiers of the gateway that has the given EUI registered.
Request type GetGatewayIdentifiersForEUIRequest
Response type GatewayIdentifiers
HTTP bindings

The EntityRegistrySearch service

Method EntityRegistrySearch.SearchGateways
Description Search for gateways that match the conditions specified in the request. Non-admin users will only match gateways that they have rights on.
Request type SearchGatewaysRequest
Response type Gateways
HTTP bindings

GET /api/v3/search/gateways

The GatewayAccess service

Method GatewayAccess.ListRights
Description List the rights the caller has on this gateway.
Request type GatewayIdentifiers
Response type Rights
HTTP bindings

GET /api/v3/gateways/{gateway_id}/rights
Method GatewayAccess.CreateAPIKey
Description Create an API key scoped to this gateway.
Request type CreateGatewayAPIKeyRequest
Response type APIKey
HTTP bindings

POST /api/v3/gateways/{gateway_ids.gateway_id}/api-keys
Method GatewayAccess.DeleteAPIKey
Description Delete a single API key of this gateway.
Request type DeleteGatewayAPIKeyRequest
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/gateways/{gateway_ids.gateway_id}/api-keys/{key_id}
Method GatewayAccess.ListAPIKeys
Description List the API keys for this gateway.
Request type ListGatewayAPIKeysRequest
Response type APIKeys
HTTP bindings

GET /api/v3/gateways/{gateway_ids.gateway_id}/api-keys
Method GatewayAccess.GetAPIKey
Description Get a single API key of this gateway.
Request type GetGatewayAPIKeyRequest
Response type APIKey
HTTP bindings

GET /api/v3/gateways/{gateway_ids.gateway_id}/api-keys/{key_id}
Method GatewayAccess.UpdateAPIKey
Description Update the rights of an API key of the gateway. This method can also be used to delete the API key, by giving it no rights. The caller is required to have all assigned or/and removed rights.
Request type UpdateGatewayAPIKeyRequest
Response type APIKey
HTTP bindings

PUT /api/v3/gateways/{gateway_ids.gateway_id}/api-keys/{api_key.id}
Method GatewayAccess.GetCollaborator
Description Get the rights of a collaborator (member) of the gateway. Pseudo-rights in the response (such as the “_ALL” right) are not expanded.
Request type GetGatewayCollaboratorRequest
Response type GetCollaboratorResponse
HTTP bindings

/api/v3

GET /api/v3/gateways/{gateway_ids.gateway_id}/collaborator/user/{collaborator.user_ids.user_id}

GET /api/v3/gateways/{gateway_ids.gateway_id}/collaborator/organization/{collaborator.organization_ids.organization_id}
Method GatewayAccess.DeleteCollaborator
Description DeleteCollaborator removes a collaborator from a gateway.
Request type DeleteGatewayCollaboratorRequest
Response type google.protobuf.Empty
HTTP bindings

/api/v3

DELETE /api/v3/gateways/{gateway_ids.gateway_id}/collaborators/user/{collaborator_ids.user_ids.user_id}

DELETE /api/v3/gateways/{gateway_ids.gateway_id}/collaborators/organization/{collaborator_ids.organization_ids.organization_id}
Method GatewayAccess.SetCollaborator
Description Set the rights of a collaborator (member) on the gateway. This method can also be used to delete the collaborator, by giving them no rights. The caller is required to have all assigned or/and removed rights.
Request type SetGatewayCollaboratorRequest
Response type google.protobuf.Empty
HTTP bindings

PUT /api/v3/gateways/{gateway_ids.gateway_id}/collaborators
Method GatewayAccess.ListCollaborators
Description List the collaborators on this gateway.
Request type ListGatewayCollaboratorsRequest
Response type Collaborators
HTTP bindings

GET /api/v3/gateways/{gateway_ids.gateway_id}/collaborators

The Configuration service

The Gateway Server exposes the list of available frequency plans with the Configuration service.

Method Configuration.ListBands
Request type ListBandsRequest
Response type ListBandsResponse
HTTP bindings

GET /api/v3/configuration/bands

GET /api/v3/configuration/bands/{band_id}

GET /api/v3/configuration/bands/{band_id}/{phy_version}
Method Configuration.ListFrequencyPlans
Request type ListFrequencyPlansRequest
Response type ListFrequencyPlansResponse
HTTP bindings

GET /api/v3/configuration/frequency-plans
Method Configuration.GetPhyVersions
Description Returns a list of supported LoRaWAN PHY Versions for the given Band ID.
Request type GetPhyVersionsRequest
Response type GetPhyVersionsResponse
HTTP bindings

GET /api/v3/configuration/phy-versions

The GatewayClaimingServer service

Method GatewayClaimingServer.AuthorizeGateway
Description AuthorizeGateway allows a gateway to be claimed. DEPRECATED: Authorizing gateways for claiming is no longer supported and will be removed in a future version of The Things Stack.
Request type AuthorizeGatewayRequest
Response type google.protobuf.Empty
HTTP bindings

POST /api/v3/gcls/gateways/{gateway_ids.gateway_id}/authorize
Method GatewayClaimingServer.Claim
Description Claims a gateway by claim authentication code or QR code and transfers the gateway to the target user.
Request type ClaimGatewayRequest
Response type GatewayIdentifiers
HTTP bindings

POST /api/v3/gcls/claim
Method GatewayClaimingServer.GetInfoByGatewayEUI
Description Return whether claiming is available for a given gateway EUI.
Request type GetInfoByGatewayEUIRequest
Response type GetInfoByGatewayEUIResponse
HTTP bindings

POST /api/v3/gcls/claim/info
Method GatewayClaimingServer.UnauthorizeGateway
Description UnauthorizeGateway prevents a gateway from being claimed. DEPRECATED: Unauthorizing (locking) gateways for claiming is no longer supported and will be removed in a future version of The Things Stack.
Request type GatewayIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/gcls/gateways/{gateway_id}/authorize

Messages

Message AlertNotificationProfileIdentifiers

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

Fields:

Field profile_id
Type string
Description

max_len: 36

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

Message APIKey

Show object example 
{
  "id": "",
  "key": "",
  "name": "",
  "rights": [],
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "expires_at": "0001-01-01T00:00:00Z",
}

Fields:

Field id
Type string
Description

Immutable and unique public identifier for the API key. Generated by the Access Server.
Field key
Type string
Description

Immutable and unique secret value of the API key. Generated by the Access Server.
Field name
Type string
Description

User-defined (friendly) name for the API key.

max_len: 50
Field rights
Type repeated Right
Description

Rights that are granted to this API key.

defined_only
Field created_at
Type google.protobuf. Timestamp
Field updated_at
Type google.protobuf. Timestamp
Field expires_at
Type google.protobuf. Timestamp
Description

gt_now

Message APIKeys

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

Fields:

Field api_keys
Type repeated APIKey
Description

Message AuthorizeGatewayRequest

Show object example 
{
  "gateway_ids": {},
  "api_key": "",
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field api_key
Type string
Description

min_len: 1

Message ClaimGatewayRequest

Restrictions:
  • Only one of authenticated_identifiers, qr_code can be set.
Show object example 
{
  "authenticated_identifiers": {},
  "qr_code": "",
  "collaborator": {},
  "target_gateway_id": "",
  "target_gateway_server_address": "",
  "cups_redirection": {},
  "target_frequency_plan_id": "",
  "target_frequency_plan_ids": [],
}

Fields:

Field authenticated_identifiers
Type ClaimGatewayRequest.AuthenticatedIdentifiers
Field qr_code
Type bytes
Description

max_len: 1024
Field collaborator
Type OrganizationOrUserIdentifiers
Description

Collaborator to grant all rights on the target gateway.

required
Field target_gateway_id
Type string
Description

Gateway ID for the target gateway. This must be a unique value. If this is not set, the target ID for the target gateway will be set to <gateway-eui>.

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$|^$
Field target_gateway_server_address
Type string
Description

Target Gateway Server Address for the target gateway.

pattern: ^(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*(?:[A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])(?::[0-9]{1,5})?$|^$
Field cups_redirection
Type CUPSRedirection
Description

Parameters to set CUPS redirection for the gateway. DEPRECATED: This field is deprecated and will be removed in a future version of The Things Stack.
Field target_frequency_plan_id
Type string
Description

Frequency plan ID of the target gateway. TODO: Remove this field (https://github.com/TheThingsIndustries/lorawan-stack/issues/4024) DEPRECATED: Use target_frequency_plan_ids instead.

max_len: 64
Field target_frequency_plan_ids
Type repeated string
Description

Frequency plan IDs of the target gateway.

max_items: 8

max_len: 64

Message ClaimGatewayRequest.AuthenticatedIdentifiers

Show object example 
{
  "gateway_eui": "",
  "authentication_code": "",
}

Fields:

Field gateway_eui
Type bytes
Description

ignore_empty

len: 8
Field authentication_code
Type bytes
Description

max_len: 2048

Message Collaborator

Show object example 
{
  "ids": {},
  "rights": [],
}

Fields:

Field ids
Type OrganizationOrUserIdentifiers
Description

required
Field rights
Type repeated Right
Description

defined_only

Message Collaborators

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

Fields:

Field collaborators
Type repeated Collaborator
Description

Message ContactInfo

Show object example 
{
  "contact_type": "CONTACT_TYPE_OTHER",
  "contact_method": "CONTACT_METHOD_OTHER",
  "value": "",
  "public": false,
  "validated_at": "0001-01-01T00:00:00Z",
}

Fields:

Field contact_type
Type ContactType
Description

defined_only
Field contact_method
Type ContactMethod
Description

defined_only
Field value
Type string
Description

max_len: 256
Field public
Type bool
Field validated_at
Type google.protobuf. Timestamp

Message CreateGatewayAPIKeyRequest

Show object example 
{
  "gateway_ids": {},
  "name": "",
  "rights": [],
  "expires_at": "0001-01-01T00:00:00Z",
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field name
Type string
Description

max_len: 50
Field rights
Type repeated Right
Description

min_items: 1

unique

defined_only
Field expires_at
Type google.protobuf. Timestamp
Description

gt_now

Message CreateGatewayRequest

Show object example 
{
  "gateway": {},
  "collaborator": {},
}

Fields:

Field gateway
Type Gateway
Description

required
Field collaborator
Type OrganizationOrUserIdentifiers
Description

Collaborator to grant all rights on the newly created gateway.

required

Message CUPSRedirection

DEPRECATED: This message is deprecated and will be removed in a future version of The Things Stack.

Restrictions:
  • Only one of client_tls, auth_token can be set.
Show object example 
{
  "target_cups_uri": "",
  "current_gateway_key": "",
  "target_cups_trust": "",
  "client_tls": {},
  "auth_token": "",
}

Fields:

Field target_cups_uri
Type string
Description

CUPS URI for LoRa Basics Station CUPS redirection.

max_len: 256

pattern: ^https

uri
Field current_gateway_key
Type string
Description

The key set in the gateway to authenticate itself.

max_len: 2048
Field target_cups_trust
Type bytes
Description

Optional PEM encoded CA Root certificate. If this field is empty, DCS will attempt to dial the Target CUPS server and fetch the CA.
Field client_tls
Type CUPSRedirection.ClientTLS
Description

TODO: Support mTLS (https://github.com/TheThingsNetwork/lorawan-stack/issues/137)
Field auth_token
Type string
Description

The Device Claiming Server will fill this field with a The Things Stack API Key.

max_len: 2048

Message CUPSRedirection.ClientTLS

Show object example 
{
  "cert": "",
  "key": "",
}

Fields:

Field cert
Type bytes
Description

PEM encoded Client Certificate.

max_len: 8192
Field key
Type bytes
Description

PEM encoded Client Private Key.

max_len: 8192

Message DeleteGatewayAPIKeyRequest

Show object example 
{
  "gateway_ids": {},
  "key_id": "",
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field key_id
Type string

Message DeleteGatewayCollaboratorRequest

Show object example 
{
  "gateway_ids": {},
  "collaborator_ids": {},
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field collaborator_ids
Type OrganizationOrUserIdentifiers
Description

required

Message FrequencyPlanDescription

Show object example 
{
  "id": "",
  "base_id": "",
  "name": "",
  "base_frequency": 0,
  "band_id": "",
}

Fields:

Field id
Type string
Field base_id
Type string
Description

The ID of the frequency that the current frequency plan is based on.
Field name
Type string
Field base_frequency
Type uint32
Description

Base frequency in MHz for hardware support (433, 470, 868 or 915)
Field band_id
Type string

Message Gateway.LRFHSS

LR-FHSS gateway capabilities.

Show object example 
{
  "supported": false,
}

Fields:

Field supported
Type bool
Description

The gateway supports the LR-FHSS uplink channels.

Message Gateway

Gateway is the message that defines a gateway on the network.

Show object example 
{
  "ids": {},
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "deleted_at": "0001-01-01T00:00:00Z",
  "name": "",
  "description": "",
  "attributes": {},
  "contact_info": [],
  "administrative_contact": {},
  "technical_contact": {},
  "version_ids": {},
  "gateway_server_address": "",
  "auto_update": false,
  "update_channel": "",
  "frequency_plan_id": "",
  "frequency_plan_ids": [],
  "antennas": [],
  "status_public": false,
  "location_public": false,
  "schedule_downlink_late": false,
  "enforce_duty_cycle": false,
  "downlink_path_constraint": "DOWNLINK_PATH_CONSTRAINT_NONE",
  "schedule_anytime_delay": "0s",
  "update_location_from_status": false,
  "lbs_lns_secret": {},
  "claim_authentication_code": {},
  "target_cups_uri": "",
  "target_cups_key": {},
  "require_authenticated_connection": false,
  "lrfhss": {},
  "disable_packet_broker_forwarding": false,
  "alert_notification_profile_ids": {},
}

Fields:

Field ids
Type GatewayIdentifiers
Description

The identifiers of the gateway. These are public and can be seen by any authenticated user in the network.

required
Field created_at
Type google.protobuf. Timestamp
Description

When the gateway was created. This information is public and can be seen by any authenticated user in the network.
Field updated_at
Type google.protobuf. Timestamp
Description

When the gateway was last updated. This information is public and can be seen by any authenticated user in the network.
Field deleted_at
Type google.protobuf. Timestamp
Description

When the gateway was deleted. This information is public and can be seen by any authenticated user in the network.
Field name
Type string
Description

The name of the gateway. This information is public and can be seen by any authenticated user in the network.

max_len: 50
Field description
Type string
Description

A description for the gateway. This information is public and can be seen by any authenticated user in the network.

max_len: 2000
Field attributes
Type map of string to string
Description

Key-value attributes for this gateway. Typically used for organizing gateways or for storing integration-specific data.

max_pairs: 10

max_len (key): 36

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

max_len (value): 200
Field contact_info
Type repeated ContactInfo
Description

Contact information for this gateway. Typically used to indicate who to contact with technical/security questions about the gateway. This field is deprecated. Use administrative_contact and technical_contact instead.

max_items: 10
Field administrative_contact
Type OrganizationOrUserIdentifiers
Field technical_contact
Type OrganizationOrUserIdentifiers
Field version_ids
Type GatewayVersionIdentifiers
Field gateway_server_address
Type string
Description

The address of the Gateway Server to connect to. This information is public and can be seen by any authenticated user in the network if status_public is true. The typical format of the address is “scheme://host:port”. The scheme is optional. If the port is omitted, the normal port inference (with DNS lookup, otherwise defaults) is used. The connection shall be established with transport layer security (TLS). Custom certificate authorities may be configured out-of-band.

pattern: ^([a-z]{2,5}://)?(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*(?:[A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9\-]*[A-Za-z0-9])(?::[0-9]{1,5})?$|^$
Field auto_update
Type bool
Field update_channel
Type string
Description

max_len: 128
Field frequency_plan_id
Type string
Description

Frequency plan ID of the gateway. This information is public and can be seen by any authenticated user in the network. DEPRECATED: use frequency_plan_ids. This equals the first element of the frequency_plan_ids field.

max_len: 64
Field frequency_plan_ids
Type repeated string
Description

Frequency plan IDs of the gateway. This information is public and can be seen by any authenticated user in the network. The first element equals the frequency_plan_id field.

max_items: 8

max_len: 64
Field antennas
Type repeated GatewayAntenna
Description

Antennas of the gateway. Location information of the antennas is public and can be seen by any authenticated user in the network if location_public=true.

max_items: 8
Field status_public
Type bool
Description

The status of this gateway may be publicly displayed.
Field location_public
Type bool
Description

The location of this gateway may be publicly displayed.
Field schedule_downlink_late
Type bool
Description

Enable server-side buffering of downlink messages. This is recommended for gateways using the Semtech UDP Packet Forwarder v2.x or older, as it does not feature a just-in-time queue. If enabled, the Gateway Server schedules the downlink message late to the gateway so that it does not overwrite previously scheduled downlink messages that have not been transmitted yet.
Field enforce_duty_cycle
Type bool
Description

Enforcing gateway duty cycle is recommended for all gateways to respect spectrum regulations. Disable enforcing the duty cycle only in controlled research and development environments.
Field downlink_path_constraint
Type DownlinkPathConstraint
Description

defined_only
Field schedule_anytime_delay
Type google.protobuf. Duration
Description

Adjust the time that GS schedules class C messages in advance. This is useful for gateways that have a known high latency backhaul, like 3G and satellite.
Field update_location_from_status
Type bool
Description

Update the location of this gateway from status messages. This only works for gateways connecting with authentication; gateways connected over UDP are not supported.
Field lbs_lns_secret
Type Secret
Description

The LoRa Basics Station LNS secret. This is either an auth token (such as an API Key) or a TLS private certificate. Requires the RIGHT_GATEWAY_READ_SECRETS for reading and RIGHT_GATEWAY_WRITE_SECRETS for updating this value.
Field claim_authentication_code
Type GatewayClaimAuthenticationCode
Description

The authentication code for gateway claiming. Requires the RIGHT_GATEWAY_READ_SECRETS for reading and RIGHT_GATEWAY_WRITE_SECRETS for updating this value. The entire field must be used in RPCs since sub-fields are validated wrt to each other. Direct selection/update of sub-fields only are not allowed. Use the top level field mask claim_authentication_code even when updating single fields.
Field target_cups_uri
Type string
Description

CUPS URI for LoRa Basics Station CUPS redirection. The CUPS Trust field will be automatically fetched from the cert chain presented by the target server.

ignore_empty

uri
Field target_cups_key
Type Secret
Description

CUPS Key for LoRa Basics Station CUPS redirection. If redirecting to another instance of TTS, use the CUPS API Key for the gateway on the target instance. Requires the RIGHT_GATEWAY_READ_SECRETS for reading and RIGHT_GATEWAY_WRITE_SECRETS for updating this value.
Field require_authenticated_connection
Type bool
Description

Require an authenticated gateway connection. This prevents the gateway from using the UDP protocol and requires authentication when using other protocols.
Field lrfhss
Type Gateway.LRFHSS
Field disable_packet_broker_forwarding
Type bool
Field alert_notification_profile_ids
Type AlertNotificationProfileIdentifiers
Description

next: 33

Message GatewayAntenna

GatewayAntenna is the message that defines a gateway antenna.

Show object example 
{
  "gain": 0,
  "location": {},
  "attributes": {},
  "placement": "PLACEMENT_UNKNOWN",
}

Fields:

Field gain
Type float
Description

Antenna gain relative to the gateway, in dBi.
Field location
Type Location
Description

location is the antenna’s location.
Field attributes
Type map of string to string
Description

max_pairs: 10

max_len (key): 36

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

max_len (value): 200
Field placement
Type GatewayAntennaPlacement

Message GatewayIdentifiers

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

Fields:

Field gateway_id
Type string
Description

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){2,}$
Field eui
Type bytes
Description

Secondary identifier, which can only be used in specific requests.

ignore_empty

len: 8

Message Gateways

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

Fields:

Field gateways
Type repeated Gateway
Description

Message GatewayVersionIdentifiers

Identifies an end device model with version information.

Show object example 
{
  "brand_id": "",
  "model_id": "",
  "hardware_version": "",
  "firmware_version": "",
  "runtime_version": "",
}

Fields:

Field brand_id
Type string
Description

ignore_empty

max_len: 36

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

ignore_empty

max_len: 36

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

max_len: 32
Field firmware_version
Type string
Description

max_len: 32
Field runtime_version
Type string
Description

max_len: 32

Message GatewayClaimAuthenticationCode

Authentication code for claiming gateways.

Show object example 
{
  "secret": {},
  "valid_from": "0001-01-01T00:00:00Z",
  "valid_to": "0001-01-01T00:00:00Z",
}

Fields:

Field secret
Type Secret
Field valid_from
Type google.protobuf. Timestamp
Field valid_to
Type google.protobuf. Timestamp

Message GetCollaboratorResponse

Show object example 
{
  "ids": {},
  "rights": [],
}

Fields:

Field ids
Type OrganizationOrUserIdentifiers
Field rights
Type repeated Right
Description

Message GetGatewayAPIKeyRequest

Show object example 
{
  "gateway_ids": {},
  "key_id": "",
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field key_id
Type string
Description

Unique public identifier for the API key.

Message GetGatewayCollaboratorRequest

Show object example 
{
  "gateway_ids": {},
  "collaborator": {},
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field collaborator
Type OrganizationOrUserIdentifiers
Description

required

Message GetGatewayRequest

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

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the gateway fields that should be returned.

Message GetGatewayIdentifiersForEUIRequest

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

Fields:

Field eui
Type bytes
Description

ignore_empty

len: 8

Message GetInfoByGatewayEUIRequest

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

Fields:

Field eui
Type bytes
Description

ignore_empty

len: 8

Message GetPhyVersionsRequest

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

Fields:

Field band_id
Type string
Description

Optional Band ID to filter the results. If unused, all supported Bands and their versions are returned.

Message ListBandsRequest

Show object example 
{
  "band_id": "",
  "phy_version": "PHY_UNKNOWN",
}

Fields:

Field band_id
Type string
Description

Optional Band ID to filter the results. If unused, all supported Bands are returned.
Field phy_version
Type PHYVersion
Description

Optional PHY version to filter the results. If unused, all supported versions are returned.

defined_only

Message ListFrequencyPlansRequest

Show object example 
{
  "base_frequency": 0,
  "band_id": "",
  "gateways_only": false,
}

Fields:

Field base_frequency
Type uint32
Description

Optional base frequency in MHz for hardware support (433, 470, 868 or 915)
Field band_id
Type string
Description

Optional Band ID to filter the results.
Field gateways_only
Type bool
Description

Optional field to include only gateway related results.

Message ListFrequencyPlansResponse

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

Fields:

Field frequency_plans
Type repeated FrequencyPlanDescription
Description

Message ListGatewayAPIKeysRequest

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

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field order
Type string
Description

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

in: [ api_key_id -api_key_id name -name created_at -created_at expires_at -expires_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 ListGatewayCollaboratorsRequest

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

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
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 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: [ id -id -rights rights]

Message ListGatewaysRequest

Show object example 
{
  "collaborator": {},
  "field_mask": {},
  "order": "",
  "limit": 0,
  "page": 0,
  "deleted": false,
  "filters": [],
}

Fields:

Field collaborator
Type OrganizationOrUserIdentifiers
Description

By default we list all gateways the caller has rights on. Set the user or the organization (not both) to instead list the gateways where the user or organization is collaborator on.
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the gateway fields that should be returned.
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: [ gateway_id -gateway_id gateway_eui -gateway_eui 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 gateways.
Field filters
Type repeated ListGatewaysRequest.Filter
Description

Message ListGatewaysRequest.Filter

Filter gateways by fields.

Restrictions:
  • Only one of updated_since can be set.
Show object example 
{
  "updated_since": "0001-01-01T00:00:00Z",
}

Fields:

Field updated_since
Type google.protobuf. Timestamp
Description

lt_now

Message Location

Show object example 
{
  "latitude": 0,
  "longitude": 0,
  "altitude": 0,
  "accuracy": 0,
  "source": "SOURCE_UNKNOWN",
}

Fields:

Field latitude
Type double
Description

The North–South position (degrees; -90 to +90), where 0 is the equator, North pole is positive, South pole is negative.

gte: -90

lte: 90
Field longitude
Type double
Description

The East-West position (degrees; -180 to +180), where 0 is the Prime Meridian (Greenwich), East is positive , West is negative.

gte: -180

lte: 180
Field altitude
Type int32
Description

The altitude (meters), where 0 is the mean sea level.
Field accuracy
Type int32
Description

The accuracy of the location (meters).
Field source
Type LocationSource
Description

Source of the location information.

defined_only

Message OrganizationOrUserIdentifiers

OrganizationOrUserIdentifiers contains either organization or user identifiers.

Restrictions:
  • Only one of organization_ids, user_ids can be set.
Show object example 
{
  "organization_ids": {},
  "user_ids": {},
}

Fields:

Field organization_ids
Type OrganizationIdentifiers
Field user_ids
Type UserIdentifiers

Message OrganizationIdentifiers

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

Fields:

Field organization_id
Type string
Description

This ID shares namespace with user IDs.

max_len: 36

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

Message Rights

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

Fields:

Field rights
Type repeated Right
Description

defined_only

Message SearchGatewaysRequest

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

Show object example 
{
  "query": "",
  "id_contains": "",
  "name_contains": "",
  "description_contains": "",
  "attributes_contain": {},
  "eui_contains": "",
  "field_mask": {},
  "order": "",
  "limit": 0,
  "page": 0,
  "deleted": false,
}

Fields:

Field query
Type string
Description

Find gateways where the ID, name, description or EUI contains this substring.

max_len: 50
Field id_contains
Type string
Description

Find gateways where the ID contains this substring.

max_len: 50
Field name_contains
Type string
Description

Find gateways where the name contains this substring.

max_len: 50
Field description_contains
Type string
Description

Find gateways where the description contains this substring.

max_len: 50
Field attributes_contain
Type map of string to string
Description

Find gateways 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 eui_contains
Type string
Description

Find gateways where the (hexadecimal) EUI contains this substring.

max_len: 16
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: [ gateway_id -gateway_id gateway_eui -gateway_eui 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 gateways.

Message SetGatewayCollaboratorRequest

Show object example 
{
  "gateway_ids": {},
  "collaborator": {},
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field collaborator
Type Collaborator
Description

required

Message UpdateGatewayAPIKeyRequest

Show object example 
{
  "gateway_ids": {},
  "api_key": {},
  "field_mask": {},
}

Fields:

Field gateway_ids
Type GatewayIdentifiers
Description

required
Field api_key
Type APIKey
Description

required
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the api key fields that should be updated.

Message UpdateGatewayRequest

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

Fields:

Field gateway
Type Gateway
Description

required
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the gateway fields that should be updated.

Message UserIdentifiers

Show object example 
{
  "user_id": "",
  "email": "",
}

Fields:

Field user_id
Type string
Description

This ID shares namespace with organization IDs.

max_len: 36

pattern: ^[a-z0-9](?:[-]?[a-z0-9]){1,}$
Field email
Type string
Description

Secondary identifier, which can only be used in specific requests.

Message Secret

Secret contains a secret value. It also contains the ID of the Encryption key used to encrypt it.

Show object example 
{
  "key_id": "",
  "value": "",
}

Fields:

Field key_id
Type string
Description

ID of the Key used to encrypt the secret.
Field value
Type bytes
Description

max_len: 2048

Enums

Enum ContactType

Name Value Description
CONTACT_TYPE_OTHER 0
CONTACT_TYPE_ABUSE 1
CONTACT_TYPE_BILLING 2
CONTACT_TYPE_TECHNICAL 3

Enum ContactMethod

Name Value Description
CONTACT_METHOD_OTHER 0
CONTACT_METHOD_EMAIL 1
CONTACT_METHOD_PHONE 2

Enum DownlinkPathConstraint

Name Value Description
DOWNLINK_PATH_CONSTRAINT_NONE 0 Indicates that the gateway can be selected for downlink without constraints by the Network Server.
DOWNLINK_PATH_CONSTRAINT_PREFER_OTHER 1 Indicates that the gateway can be selected for downlink only if no other or better gateway can be selected.
DOWNLINK_PATH_CONSTRAINT_NEVER 2 Indicates that this gateway will never be selected for downlink, even if that results in no available downlink path.

Enum GatewayAntennaPlacement

Name Value Description
PLACEMENT_UNKNOWN 0
INDOOR 1
OUTDOOR 2

Enum LocationSource

Name Value Description
SOURCE_UNKNOWN 0 The source of the location is not known or not set.
SOURCE_GPS 1 The location is determined by GPS.
SOURCE_REGISTRY 3 The location is set in and updated from a registry.
SOURCE_IP_GEOLOCATION 4 The location is estimated with IP geolocation.
SOURCE_WIFI_RSSI_GEOLOCATION 5 The location is estimated with WiFi RSSI geolocation.
SOURCE_BT_RSSI_GEOLOCATION 6 The location is estimated with BT/BLE RSSI geolocation.
SOURCE_LORA_RSSI_GEOLOCATION 7 The location is estimated with LoRa RSSI geolocation.
SOURCE_LORA_TDOA_GEOLOCATION 8 The location is estimated with LoRa TDOA geolocation.
SOURCE_COMBINED_GEOLOCATION 9 The location is estimated by a combination of geolocation sources.

Enum PHYVersion

Name Value Description
PHY_UNKNOWN 0
PHY_V1_0 1
TS001_V1_0 1
PHY_V1_0_1 2
TS001_V1_0_1 2
PHY_V1_0_2_REV_A 3
RP001_V1_0_2 3
PHY_V1_0_2_REV_B 4
RP001_V1_0_2_REV_B 4
PHY_V1_1_REV_A 5
RP001_V1_1_REV_A 5
PHY_V1_1_REV_B 6
RP001_V1_1_REV_B 6
PHY_V1_0_3_REV_A 7
RP001_V1_0_3_REV_A 7
RP002_V1_0_0 8
RP002_V1_0_1 9
RP002_V1_0_2 10
RP002_V1_0_3 11
RP002_V1_0_4 12

Enum Right

Right is the enum that defines all the different rights to do something in the network.

Name Value Description
right_invalid 0
RIGHT_USER_INFO 1 The right to view user information.
RIGHT_USER_SETTINGS_BASIC 2 The right to edit basic user settings.
RIGHT_USER_SETTINGS_API_KEYS 3 The right to view and edit user API keys.
RIGHT_USER_DELETE 4 The right to delete user account.
RIGHT_USER_AUTHORIZED_CLIENTS 5 The right to view and edit authorized OAuth clients of the user.
RIGHT_USER_APPLICATIONS_LIST 6 The right to list applications the user is a collaborator of.
RIGHT_USER_APPLICATIONS_CREATE 7 The right to create an application under the user account.
RIGHT_USER_GATEWAYS_LIST 8 The right to list gateways the user is a collaborator of.
RIGHT_USER_GATEWAYS_CREATE 9 The right to create a gateway under the account of the user.
RIGHT_USER_CLIENTS_LIST 10 The right to list OAuth clients the user is a collaborator of.
RIGHT_USER_CLIENTS_CREATE 11 The right to create an OAuth client under the account of the user.
RIGHT_USER_ORGANIZATIONS_LIST 12 The right to list organizations the user is a member of.
RIGHT_USER_ORGANIZATIONS_CREATE 13 The right to create an organization under the user account.
RIGHT_USER_NOTIFICATIONS_READ 59 The right to read notifications sent to the user.
RIGHT_USER_ALL 14 The pseudo-right for all (current and future) user rights.
RIGHT_APPLICATION_INFO 15 The right to view application information.
RIGHT_APPLICATION_SETTINGS_BASIC 16 The right to edit basic application settings.
RIGHT_APPLICATION_SETTINGS_API_KEYS 17 The right to view and edit application API keys.
RIGHT_APPLICATION_SETTINGS_COLLABORATORS 18 The right to view and edit application collaborators.
RIGHT_APPLICATION_SETTINGS_PACKAGES 56 The right to view and edit application packages and associations.
RIGHT_APPLICATION_DELETE 19 The right to delete application.
RIGHT_APPLICATION_DEVICES_READ 20 The right to view devices in application.
RIGHT_APPLICATION_DEVICES_WRITE 21 The right to create devices in application.
RIGHT_APPLICATION_DEVICES_READ_KEYS 22 The right to view device keys in application. Note that keys may not be stored in a way that supports viewing them.
RIGHT_APPLICATION_DEVICES_WRITE_KEYS 23 The right to edit device keys in application.
RIGHT_APPLICATION_TRAFFIC_READ 24 The right to read application traffic (uplink and downlink).
RIGHT_APPLICATION_TRAFFIC_UP_WRITE 25 The right to write uplink application traffic.
RIGHT_APPLICATION_TRAFFIC_DOWN_WRITE 26 The right to write downlink application traffic.
RIGHT_APPLICATION_LINK 27 The right to link as Application to a Network Server for traffic exchange, i.e. read uplink and write downlink (API keys only). This right is typically only given to an Application Server. This right implies RIGHT_APPLICATION_INFO, RIGHT_APPLICATION_TRAFFIC_READ, and RIGHT_APPLICATION_TRAFFIC_DOWN_WRITE.
RIGHT_APPLICATION_ALL 28 The pseudo-right for all (current and future) application rights.
RIGHT_CLIENT_ALL 29 The pseudo-right for all (current and future) OAuth client rights.
RIGHT_CLIENT_INFO 60 The right to read client information.
RIGHT_CLIENT_SETTINGS_BASIC 61 The right to edit basic client settings.
RIGHT_CLIENT_SETTINGS_COLLABORATORS 62 The right to view and edit client collaborators.
RIGHT_CLIENT_DELETE 63 The right to delete a client.
RIGHT_GATEWAY_INFO 30 The right to view gateway information.
RIGHT_GATEWAY_SETTINGS_BASIC 31 The right to edit basic gateway settings.
RIGHT_GATEWAY_SETTINGS_API_KEYS 32 The right to view and edit gateway API keys.
RIGHT_GATEWAY_SETTINGS_COLLABORATORS 33 The right to view and edit gateway collaborators.
RIGHT_GATEWAY_DELETE 34 The right to delete gateway.
RIGHT_GATEWAY_TRAFFIC_READ 35 The right to read gateway traffic.
RIGHT_GATEWAY_TRAFFIC_DOWN_WRITE 36 The right to write downlink gateway traffic.
RIGHT_GATEWAY_LINK 37 The right to link as Gateway to a Gateway Server for traffic exchange, i.e. write uplink and read downlink (API keys only) This right is typically only given to a gateway. This right implies RIGHT_GATEWAY_INFO.
RIGHT_GATEWAY_STATUS_READ 38 The right to view gateway status.
RIGHT_GATEWAY_LOCATION_READ 39 The right to view view gateway location.
RIGHT_GATEWAY_WRITE_SECRETS 57 The right to store secrets associated with this gateway.
RIGHT_GATEWAY_READ_SECRETS 58 The right to retrieve secrets associated with this gateway.
RIGHT_GATEWAY_ALL 40 The pseudo-right for all (current and future) gateway rights.
RIGHT_ORGANIZATION_INFO 41 The right to view organization information.
RIGHT_ORGANIZATION_SETTINGS_BASIC 42 The right to edit basic organization settings.
RIGHT_ORGANIZATION_SETTINGS_API_KEYS 43 The right to view and edit organization API keys.
RIGHT_ORGANIZATION_SETTINGS_MEMBERS 44 The right to view and edit organization members.
RIGHT_ORGANIZATION_DELETE 45 The right to delete organization.
RIGHT_ORGANIZATION_APPLICATIONS_LIST 46 The right to list the applications the organization is a collaborator of.
RIGHT_ORGANIZATION_APPLICATIONS_CREATE 47 The right to create an application under the organization.
RIGHT_ORGANIZATION_GATEWAYS_LIST 48 The right to list the gateways the organization is a collaborator of.
RIGHT_ORGANIZATION_GATEWAYS_CREATE 49 The right to create a gateway under the organization.
RIGHT_ORGANIZATION_CLIENTS_LIST 50 The right to list the OAuth clients the organization is a collaborator of.
RIGHT_ORGANIZATION_CLIENTS_CREATE 51 The right to create an OAuth client under the organization.
RIGHT_ORGANIZATION_ADD_AS_COLLABORATOR 52 The right to add the organization as a collaborator on an existing entity.
RIGHT_ORGANIZATION_ALL 53 The pseudo-right for all (current and future) organization rights.
RIGHT_SEND_INVITES 54 The right to send invites to new users. Note that this is not prefixed with “USER_”; it is not a right on the user entity.
RIGHT_ALL 55 The pseudo-right for all (current and future) possible rights.
← Events API Gateway Server APIs →