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 given by the field mask. The method may return more or less fields, 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. See request message for details.
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

Method GatewayRegistry.Update
Request type UpdateGatewayRequest
Response type Gateway
HTTP bindings

PUT /api/v3/gateways/{gateway.ids.gateway_id}

Method GatewayRegistry.Delete
Request type GatewayIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/gateways/{gateway_id}

The EntityRegistrySearch service

Method EntityRegistrySearch.SearchGateways
Request type SearchEntitiesRequest
Response type Gateways
HTTP bindings

GET /api/v3/search/gateways

The GatewayAccess service

Method GatewayAccess.ListRights
Request type GatewayIdentifiers
Response type Rights
HTTP bindings

GET /api/v3/gateways/{gateway_id}/rights

Method GatewayAccess.CreateAPIKey
Request type CreateGatewayAPIKeyRequest
Response type APIKey
HTTP bindings

POST /api/v3/gateways/{gateway_ids.gateway_id}/api-keys

Method GatewayAccess.ListAPIKeys
Request type ListGatewayAPIKeysRequest
Response type APIKeys
HTTP bindings

GET /api/v3/gateways/{gateway_ids.gateway_id}/api-keys

Method GatewayAccess.GetAPIKey
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 existing gateway API key. To generate an API key, the CreateAPIKey should be used. To delete an API key, update it with zero rights. It is required for the caller 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

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

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.SetCollaborator
Description Set the rights of a collaborator (member) on the gateway. It is required for the caller to have all assigned or/and removed rights. Setting a collaborator without rights, removes them.
Request type SetGatewayCollaboratorRequest
Response type google.protobuf.Empty
HTTP bindings

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

Method GatewayAccess.ListCollaborators
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.ListFrequencyPlans
Request type ListFrequencyPlansRequest
Response type ListFrequencyPlansResponse
HTTP bindings

GET /api/v3/configuration/frequency-plans

Messages

Message APIKey

Field Type Description
id string

Immutable and unique public identifier for the API key. Generated by the Access Server.

key string

Immutable and unique secret value of the API key. Generated by the Access Server.

name string

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

max_len: 50

rights repeated Right

Rights that are granted to this API key.

defined_only

Show object example
{
  "id": "",
  "key": "",
  "name": "",
  "rights": [],
}

Message APIKeys

Field Type Description
api_keys repeated APIKey
Show object example
{
  "api_keys": [],
}

Message Collaborator

Field Type Description
ids OrganizationOrUserIdentifiers

required

rights repeated Right

defined_only

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

Message Collaborators

Field Type Description
collaborators repeated Collaborator
Show object example
{
  "collaborators": [],
}

Message CreateGatewayAPIKeyRequest

Field Type Description
gateway_ids GatewayIdentifiers

required

name string

max_len: 50

rights repeated Right

defined_only

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

Message CreateGatewayRequest

Field Type Description
gateway Gateway

required

collaborator OrganizationOrUserIdentifiers

Collaborator to grant all rights on the newly created gateway.

required

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

Message FrequencyPlanDescription

Field Type Description
id string
base_id string

The ID of the frequency that the current frequency plan is based on.

name string
base_frequency uint32

Base frequency in MHz for hardware support (433, 470, 868 or 915)

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

Message Gateway

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

Field Type Description
ids GatewayIdentifiers

required

created_at google.protobuf.Timestamp
updated_at google.protobuf.Timestamp
name string

max_len: 50

description string

max_len: 2000

attributes map of string to string
contact_info repeated ContactInfo
version_ids GatewayVersionIdentifiers

required

gateway_server_address string

The address of the Gateway Server to connect to. The typical format of the address is “host:port”. 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-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})?$|^$

auto_update bool
update_channel string
frequency_plan_id string

max_len: 64

antennas repeated GatewayAntenna
status_public bool

The status of this gateway may be publicly displayed.

location_public bool

The location of this gateway may be publicly displayed.

schedule_downlink_late bool

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.

enforce_duty_cycle bool

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.

downlink_path_constraint DownlinkPathConstraint

defined_only

schedule_anytime_delay google.protobuf.Duration

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.

Show object example
{
  "ids": {},
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "name": "",
  "description": "",
  "attributes": {},
  "contact_info": [],
  "version_ids": {},
  "gateway_server_address": "",
  "auto_update": false,
  "update_channel": "",
  "frequency_plan_id": "",
  "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",
}

Message GatewayAntenna

GatewayAntenna is the message that defines a gateway antenna.

Field Type Description
gain float

gain is the antenna gain relative to this gateway, in dBi.

location Location

location is the antenna’s location.

required

attributes map of string to string
Show object example
{
  "gain": 0,
  "location": {},
  "attributes": {},
}

Message GatewayIdentifiers

Field Type Description
gateway_id string

max_len: 36

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

eui bytes

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

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

Message Gateways

Field Type Description
gateways repeated Gateway
Show object example
{
  "gateways": [],
}

Message GatewayVersionIdentifiers

Identifies an end device model with version information.

Field Type Description
brand_id string

max_len: 36

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

model_id string

max_len: 36

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

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

Message GetCollaboratorResponse

Field Type Description
ids OrganizationOrUserIdentifiers
rights repeated Right
Show object example
{
  "ids": {},
  "rights": [],
}

Message GetGatewayAPIKeyRequest

Field Type Description
gateway_ids GatewayIdentifiers

required

key_id string

Unique public identifier for the API key.

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

Message GetGatewayCollaboratorRequest

Field Type Description
gateway_ids GatewayIdentifiers

required

collaborator OrganizationOrUserIdentifiers

required

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

Message GetGatewayRequest

Field Type Description
gateway_ids GatewayIdentifiers

required

field_mask google.protobuf.FieldMask
Show object example
{
  "gateway_ids": {},
  "field_mask": {},
}

Message ListFrequencyPlansRequest

Field Type Description
base_frequency uint32

Optional base frequency in MHz for hardware support (433, 470, 868 or 915)

Show object example
{
  "base_frequency": 0,
}

Message ListFrequencyPlansResponse

Field Type Description
frequency_plans repeated FrequencyPlanDescription
Show object example
{
  "frequency_plans": [],
}

Message ListGatewayAPIKeysRequest

Field Type Description
gateway_ids GatewayIdentifiers

required

limit uint32

Limit the number of results per page.

lte: 1000

page uint32

Page number for pagination. 0 is interpreted as 1.

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

Message ListGatewayCollaboratorsRequest

Field Type Description
gateway_ids GatewayIdentifiers

required

limit uint32

Limit the number of results per page.

lte: 1000

page uint32

Page number for pagination. 0 is interpreted as 1.

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

Message ListGatewaysRequest

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

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]

limit uint32

Limit the number of results per page.

lte: 1000

page uint32

Page number for pagination. 0 is interpreted as 1.

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

Message OrganizationOrUserIdentifiers

OrganizationOrUserIdentifiers contains either organization or user identifiers.

Field Type Description
organization_ids OrganizationIdentifiers
user_ids UserIdentifiers
Restrictions
Only one of organization_ids, user_ids can be set.
Show object example
{
  "organization_ids": {},
  "user_ids": {},
}

Message Rights

Field Type Description
rights repeated Right

defined_only

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

Message SearchEntitiesRequest

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

Field Type Description
id_contains string

Find entities where the ID contains this substring.

name_contains string

Find entities where the name contains this substring.

description_contains string

Find entities where the description contains this substring.

attributes_contain map of string to string

Find entities where the given attributes contain these substrings.

field_mask google.protobuf.FieldMask
order string

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.

limit uint32

Limit the number of results per page.

lte: 1000

page uint32

Page number for pagination. 0 is interpreted as 1.

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

Message SetGatewayCollaboratorRequest

Field Type Description
gateway_ids GatewayIdentifiers

required

collaborator Collaborator

required

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

Message UpdateGatewayAPIKeyRequest

Field Type Description
gateway_ids GatewayIdentifiers

required

api_key APIKey

required

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

Message UpdateGatewayRequest

Field Type Description
gateway Gateway

required

field_mask google.protobuf.FieldMask
Show object example
{
  "gateway": {},
  "field_mask": {},
}

Message UserIdentifiers

Field Type Description
user_id string

This ID shares namespace with organization IDs.

max_len: 36

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

email string

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

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

Enums

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.