User APIs

List of User APIs.

The UserRegistry service

Method UserRegistry.Create
Description Register a new user. This method may be restricted by network settings.
Request type CreateUserRequest
Response type User
HTTP bindings

POST /api/v3/users
Method UserRegistry.Get
Description Get the user 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 GetUserRequest
Response type User
HTTP bindings

GET /api/v3/users/{user_ids.user_id}
Method UserRegistry.List
Description List users of the network. This method is typically restricted to admins only.
Request type ListUsersRequest
Response type Users
HTTP bindings

GET /api/v3/users
Method UserRegistry.Update
Description Update the user, changing the fields specified by the field mask to the provided values. This method can not be used to change the password, see the UpdatePassword method for that.
Request type UpdateUserRequest
Response type User
HTTP bindings

PUT /api/v3/users/{user.ids.user_id}
Method UserRegistry.Delete
Description Delete the user. This may not release the user ID for reuse.
Request type UserIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/users/{user_id}
Method UserRegistry.Restore
Description

Restore a recently deleted user.

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

POST /api/v3/users/{user_id}/restore
Method UserRegistry.Purge
Description Purge the user. This will release the user ID for reuse. The user is responsible for clearing data from any (external) integrations that may store and expose data by user or organization ID.
Request type UserIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/users/{user_id}/purge
Method UserRegistry.UpdatePassword
Description Update the password of the user.
Request type UpdateUserPasswordRequest
Response type google.protobuf.Empty
HTTP bindings

PUT /api/v3/users/{user_ids.user_id}/password
Method UserRegistry.CreateTemporaryPassword
Description Create a temporary password that can be used for updating a forgotten password. The generated password is sent to the user’s email address.
Request type CreateTemporaryPasswordRequest
Response type google.protobuf.Empty
HTTP bindings

POST /api/v3/users/{user_ids.user_id}/temporary_password

The ExternalUserRegistry service

Method ExternalUserRegistry.Create
Request type CreateExternalUserRequest
Response type ExternalUser
HTTP bindings

POST /api/v3/authentication_providers/{external_user.provider_ids.provider_id}/external_users
Method ExternalUserRegistry.GetByUserID
Request type GetExternalUserByUserIDRequest
Response type ExternalUser
HTTP bindings

GET /api/v3/authentication_providers/{provider_ids.provider_id}/users/{user_ids.user_id}
Method ExternalUserRegistry.GetByExternalID
Request type GetExternalUserByExternalIDRequest
Response type ExternalUser
HTTP bindings

GET /api/v3/authentication_providers/{provider_ids.provider_id}/external_users/{external_id}
Method ExternalUserRegistry.Delete
Request type DeleteExternalUserRequest
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/authentication_providers/{provider_ids.provider_id}/external_users/{external_id}

The EntityRegistrySearch service

Method EntityRegistrySearch.SearchUsers
Description Search for users that match the conditions specified in the request. This is only available to admin users.
Request type SearchUsersRequest
Response type Users
HTTP bindings

GET /api/v3/search/users

The UserAccess service

Method UserAccess.ListRights
Description List the rights the caller has on this user.
Request type UserIdentifiers
Response type Rights
HTTP bindings

GET /api/v3/users/{user_id}/rights
Method UserAccess.CreateAPIKey
Description Create an API key scoped to this user. User API keys can give access to the user itself, as well as any organization, application, gateway and OAuth client this user is a collaborator of.
Request type CreateUserAPIKeyRequest
Response type APIKey
HTTP bindings

POST /api/v3/users/{user_ids.user_id}/api-keys
Method UserAccess.DeleteAPIKey
Description Delete a single API key of this user.
Request type DeleteUserAPIKeyRequest
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/users/{user_ids.user_id}/api-keys/{key_id}
Method UserAccess.ListAPIKeys
Description List the API keys for this user.
Request type ListUserAPIKeysRequest
Response type APIKeys
HTTP bindings

GET /api/v3/users/{user_ids.user_id}/api-keys
Method UserAccess.GetAPIKey
Description Get a single API key of this user.
Request type GetUserAPIKeyRequest
Response type APIKey
HTTP bindings

GET /api/v3/users/{user_ids.user_id}/api-keys/{key_id}
Method UserAccess.UpdateAPIKey
Description Update the rights of an API key of the user. 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 UpdateUserAPIKeyRequest
Response type APIKey
HTTP bindings

PUT /api/v3/users/{user_ids.user_id}/api-keys/{api_key.id}
Method UserAccess.CreateLoginToken
Description Create a login token that can be used for a one-time login as a user.
Request type CreateLoginTokenRequest
Response type CreateLoginTokenResponse
HTTP bindings

POST /api/v3/users/{user_ids.user_id}/login-tokens

The UserInvitationRegistry service

Method UserInvitationRegistry.Send
Description Invite a user to join the network.
Request type SendInvitationRequest
Response type Invitation
HTTP bindings

POST /api/v3/invitations
Method UserInvitationRegistry.List
Description List the invitations the caller has sent.
Request type ListInvitationsRequest
Response type Invitations
HTTP bindings

GET /api/v3/invitations
Method UserInvitationRegistry.Delete
Description Delete (revoke) a user invitation.
Request type DeleteInvitationRequest
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/invitations

The UserSessionRegistry service

Method UserSessionRegistry.Delete
Description Delete (revoke) the given user session.
Request type UserSessionIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/users/{user_ids.user_id}/sessions/{session_id}
Method UserSessionRegistry.List
Description List the active sessions for the given user.
Request type ListUserSessionsRequest
Response type UserSessions
HTTP bindings

GET /api/v3/users/{user_ids.user_id}/sessions

The NotificationService service

Method NotificationService.Create
Description Create a new notification. Can only be called by internal services using cluster auth.
Request type CreateNotificationRequest
Response type CreateNotificationResponse
HTTP bindings
Method NotificationService.List
Description List the notifications for a user or an organization. When called with user credentials and empty receiver_ids, this will list notifications for the current user and its organizations.
Request type ListNotificationsRequest
Response type ListNotificationsResponse
HTTP bindings

/api/v3

GET /api/v3/users/{receiver_ids.user_id}/notifications
Method NotificationService.UpdateStatus
Description Batch-update multiple notifications to the same status.
Request type UpdateNotificationStatusRequest
Response type google.protobuf.Empty
HTTP bindings

PATCH /api/v3/users/{receiver_ids.user_id}/notifications

Messages

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 ApplicationIdentifiers

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

Fields:

Field application_id
Type string
Description

max_len: 36

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

Message AuthenticationProviderIdentifiers

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

Fields:

Field provider_id
Type string
Description

max_len: 36

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

Message ClientIdentifiers

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

Fields:

Field client_id
Type string
Description

max_len: 36

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

Message CreateUserAPIKeyRequest

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

Fields:

Field user_ids
Type UserIdentifiers
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 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 CreateLoginTokenRequest

Show object example 
{
  "user_ids": {},
  "skip_email": false,
}

Fields:

Field user_ids
Type UserIdentifiers
Description

required
Field skip_email
Type bool
Description

Skip sending the login token to the user by email. This field is only effective when the login token is created by an admin user.

Message CreateTemporaryPasswordRequest

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

Fields:

Field user_ids
Type UserIdentifiers
Description

required

Message CreateNotificationResponse

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

Fields:

Field id
Type string

Message CreateNotificationRequest

Show object example 
{
  "entity_ids": {},
  "notification_type": "",
  "data": null,
  "sender_ids": {},
  "receivers": [],
  "email": false,
}

Fields:

Field entity_ids
Type EntityIdentifiers
Description

The entity this notification is about.

required
Field notification_type
Type string
Description

The type of this notification.

in: [unknown api_key_created api_key_changed client_requested collaborator_changed entity_state_changed invitation login_token password_changed temporary_password user_requested validate support_access_requested]
Field data
Type google.protobuf. Any
Description

The data related to the notification.
Field sender_ids
Type UserIdentifiers
Description

If the notification was triggered by a user action, this contains the identifiers of the user that triggered the notification.
Field receivers
Type repeated NotificationReceiver
Description

Receivers of the notification.

min_items: 1

unique

defined_only
Field email
Type bool
Description

Whether an email should be sent for the notification.

Message CreateUserRequest

Show object example 
{
  "user": {},
  "invitation_token": "",
}

Fields:

Field user
Type User
Description

required
Field invitation_token
Type string
Description

The invitation token that was sent to the user (some networks require an invitation in order to register new users).

Message CreateExternalUserRequest

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

Fields:

Field external_user
Type ExternalUser
Description

required

Message DeleteInvitationRequest

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

Fields:

Field email
Type string
Description

email

Message DeleteUserAPIKeyRequest

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

Fields:

Field user_ids
Type UserIdentifiers
Description

required
Field key_id
Type string

Message DeleteExternalUserRequest

Show object example 
{
  "provider_ids": {},
  "external_id": "",
}

Fields:

Field provider_ids
Type AuthenticationProviderIdentifiers
Description

required
Field external_id
Type string
Description

max_len: 250

min_len: 1

Message EmailNotificationPreferences

EmailNotificationPreferences is the message that defines the types of notifications for which the user wants to receive an email.

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

Fields:

Field types
Type repeated NotificationType
Description

unique

defined_only

Message EndDeviceIdentifiers

Show object example 
{
  "device_id": "",
  "application_ids": {},
  "dev_eui": "",
  "join_eui": "",
  "dev_addr": "",
}

Fields:

Field device_id
Type string
Description

max_len: 36

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

required
Field dev_eui
Type bytes
Description

The LoRaWAN DevEUI.

ignore_empty

len: 8
Field join_eui
Type bytes
Description

The LoRaWAN JoinEUI (AppEUI until LoRaWAN 1.0.3 end devices).

ignore_empty

len: 8
Field dev_addr
Type bytes
Description

The LoRaWAN DevAddr.

ignore_empty

len: 4

Message EntityIdentifiers

EntityIdentifiers contains one of the possible entity identifiers.

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

Fields:

Field application_ids
Type ApplicationIdentifiers
Field client_ids
Type ClientIdentifiers
Field device_ids
Type EndDeviceIdentifiers
Field gateway_ids
Type GatewayIdentifiers
Field organization_ids
Type OrganizationIdentifiers
Field user_ids
Type UserIdentifiers

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 GetUserAPIKeyRequest

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

Fields:

Field user_ids
Type UserIdentifiers
Description

required
Field key_id
Type string
Description

Unique public identifier for the API key.

Message GetUserRequest

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

Fields:

Field user_ids
Type UserIdentifiers
Description

required
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the user fields that should be returned.

Message GetExternalUserByUserIDRequest

Show object example 
{
  "provider_ids": {},
  "user_ids": {},
}

Fields:

Field provider_ids
Type AuthenticationProviderIdentifiers
Description

required
Field user_ids
Type ttn.lorawan.v3. UserIdentifiers
Description

required

Message GetExternalUserByExternalIDRequest

Show object example 
{
  "provider_ids": {},
  "external_id": "",
}

Fields:

Field provider_ids
Type AuthenticationProviderIdentifiers
Description

required
Field external_id
Type string
Description

max_len: 250

min_len: 1

Message Invitation

Show object example 
{
  "email": "",
  "token": "",
  "expires_at": "0001-01-01T00:00:00Z",
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "accepted_at": "0001-01-01T00:00:00Z",
  "accepted_by": {},
}

Fields:

Field email
Type string
Description

email
Field token
Type string
Field expires_at
Type google.protobuf. Timestamp
Field created_at
Type google.protobuf. Timestamp
Field updated_at
Type google.protobuf. Timestamp
Field accepted_at
Type google.protobuf. Timestamp
Field accepted_by
Type UserIdentifiers

Message Invitations

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

Fields:

Field invitations
Type repeated Invitation
Description

Message ListNotificationsRequest

Show object example 
{
  "receiver_ids": {},
  "status": [],
  "limit": 0,
  "page": 0,
}

Fields:

Field receiver_ids
Type UserIdentifiers
Description

The IDs of the receiving user.

required
Field status
Type repeated NotificationStatus
Description

Select notifications with these statuses. An empty list is interpreted as “all”.

unique

defined_only
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 ListNotificationsResponse

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

Fields:

Field notifications
Type repeated Notification
Description

Message ListInvitationsRequest

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

Fields:

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 ListUserAPIKeysRequest

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

Fields:

Field user_ids
Type UserIdentifiers
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 ListUsersRequest

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

Fields:

Field field_mask
Type google.protobuf. FieldMask
Description

The names of the user 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: [ user_id -user_id name -name primary_email_address -primary_email_address state -state admin -admin 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 users.

Message ListUserSessionsRequest

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

Fields:

Field user_ids
Type UserIdentifiers
Description

required
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: [ 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 Notification

Show object example 
{
  "id": "",
  "created_at": "0001-01-01T00:00:00Z",
  "entity_ids": {},
  "notification_type": "",
  "data": null,
  "sender_ids": {},
  "receivers": [],
  "email": false,
  "status": "NOTIFICATION_STATUS_UNSEEN",
  "status_updated_at": "0001-01-01T00:00:00Z",
}

Fields:

Field id
Type string
Description

The immutable ID of the notification. Generated by the server.
Field created_at
Type google.protobuf. Timestamp
Description

The time when the notification was triggered.
Field entity_ids
Type EntityIdentifiers
Description

The entity this notification is about.
Field notification_type
Type string
Description

The type of this notification. TODO: Replace with type NotificationType in v4 https://github.com/TheThingsNetwork/lorawan-stack/issues/7384.

in: [unknown api_key_created api_key_changed client_requested collaborator_changed entity_state_changed invitation login_token password_changed temporary_password user_requested validate support_access_requested]
Field data
Type google.protobuf. Any
Description

The data related to the notification.
Field sender_ids
Type UserIdentifiers
Description

If the notification was triggered by a user action, this contains the identifiers of the user that triggered the notification.
Field receivers
Type repeated NotificationReceiver
Description

Relation of the notification receiver to the entity.
Field email
Type bool
Description

Whether an email was sent for the notification.
Field status
Type NotificationStatus
Description

The status of the notification.
Field status_updated_at
Type google.protobuf. Timestamp
Description

The time when the notification status was updated.

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 Picture

Show object example 
{
  "embedded": {},
  "sizes": {},
}

Fields:

Field embedded
Type Picture.Embedded
Description

Embedded picture. Omitted if there are external URLs available (in sizes).
Field sizes
Type map of uint32 to string
Description

URLs of the picture for different sizes, if available on a CDN.

uri_ref (value)

Message Picture.Embedded

Show object example 
{
  "mime_type": "",
  "data": "",
}

Fields:

Field mime_type
Type string
Description

MIME type of the picture.

max_len: 32
Field data
Type bytes
Description

Picture data. A data URI can be constructed as follows: data:<mime_type>;base64,<data>.

max_len: 8388608

Message Rights

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

Fields:

Field rights
Type repeated Right
Description

defined_only

Message SearchUsersRequest

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

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

Fields:

Field query
Type string
Description

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

max_len: 50
Field id_contains
Type string
Description

Find users where the ID contains this substring.

max_len: 50
Field name_contains
Type string
Description

Find users where the name contains this substring.

max_len: 50
Field description_contains
Type string
Description

Find users where the description contains this substring.

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

Find users 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 State
Description

Find users where the state is any of these states.

unique

defined_only
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: [ user_id -user_id name -name primary_email_address -primary_email_address state -state admin -admin 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 users.

Message SendInvitationRequest

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

Fields:

Field email
Type string
Description

email

Message UpdateNotificationStatusRequest

Show object example 
{
  "receiver_ids": {},
  "ids": [],
  "status": "NOTIFICATION_STATUS_UNSEEN",
}

Fields:

Field receiver_ids
Type UserIdentifiers
Description

The IDs of the receiving user.

required
Field ids
Type repeated string
Description

The IDs of the notifications to update the status of.

max_items: 1000

min_items: 1

unique

len: 36
Field status
Type NotificationStatus
Description

The status to set on the notifications.

defined_only

Message UpdateUserAPIKeyRequest

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

Fields:

Field user_ids
Type UserIdentifiers
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 UpdateUserPasswordRequest

Show object example 
{
  "user_ids": {},
  "new": "",
  "old": "",
  "revoke_all_access": false,
}

Fields:

Field user_ids
Type UserIdentifiers
Description

required
Field new
Type string
Description

max_len: 1000
Field old
Type string
Description

max_len: 1000
Field revoke_all_access
Type bool
Description

Revoke active sessions and access tokens of user if true. To be used if credentials are suspected to be compromised.

Message UpdateUserRequest

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

Fields:

Field user
Type User
Description

required
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the user fields that should be updated.

Message User

User is the message that defines a user 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": [],
  "primary_email_address": "",
  "primary_email_address_validated_at": "0001-01-01T00:00:00Z",
  "password": "",
  "password_updated_at": "0001-01-01T00:00:00Z",
  "require_password_update": false,
  "state": "STATE_REQUESTED",
  "state_description": "",
  "admin": false,
  "temporary_password": "",
  "temporary_password_created_at": "0001-01-01T00:00:00Z",
  "temporary_password_expires_at": "0001-01-01T00:00:00Z",
  "profile_picture": {},
  "application_limit": null,
  "client_limit": null,
  "gateway_limit": null,
  "organization_limit": null,
  "console_preferences": {},
  "email_notification_preferences": {},
  "universal_rights": [],
}

Fields:

Field ids
Type UserIdentifiers
Description

The identifiers of the user. 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 user 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 user 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 user 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 user. 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 user. 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 users. Typically used 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 user. Typically used to indicate who to contact with security/billing questions about the user. This field is deprecated.

max_items: 10
Field primary_email_address
Type string
Description

Primary email address that can be used for logging in. This address is not public, use contact_info for that.

email
Field primary_email_address_validated_at
Type google.protobuf. Timestamp
Description

When the primary email address was validated. Note that email address validation is not required on all networks.
Field password
Type string
Description

The password field is only considered when creating a user. It is not returned on API calls, and can not be updated by updating the User. See the UpdatePassword method of the UserRegistry service for more information.

max_len: 1000
Field password_updated_at
Type google.protobuf. Timestamp
Field require_password_update
Type bool
Field state
Type State
Description

The reviewing state of the user. This information is public and can be seen by any authenticated user in the network. This field can only be modified by admins.

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 admin
Type bool
Description

This user is an admin. This information is public and can be seen by any authenticated user in the network. This field can only be modified by other admins.
Field temporary_password
Type string
Description

The temporary password can only be used to update a user’s password; never returned on API calls. It is not returned on API calls, and can not be updated by updating the User. See the CreateTemporaryPassword method of the UserRegistry service for more information.

max_len: 1000
Field temporary_password_created_at
Type google.protobuf. Timestamp
Field temporary_password_expires_at
Type google.protobuf. Timestamp
Field profile_picture
Type Picture
Description

A profile picture for the user. This information is public and can be seen by any authenticated user in the network.
Field application_limit
Type google.protobuf. UInt64Value
Description

The maximum number of applications of the user. This field can only be modified by admins.
Field client_limit
Type google.protobuf. UInt64Value
Description

The maximum number of clients of the user. This field can only be modified by admins.
Field gateway_limit
Type google.protobuf. UInt64Value
Description

The maximum number of gateways of the user. This field can only be modified by admins.
Field organization_limit
Type google.protobuf. UInt64Value
Description

The maximum number of organizations of the user. This field can only be modified by admins.
Field console_preferences
Type UserConsolePreferences
Description

Console preferences contains the user’s preferences regarding the behavior of the Console.
Field email_notification_preferences
Type EmailNotificationPreferences
Field universal_rights
Type repeated Right
Description

Universal rights are capable of restricting the user’s interactions with the API, be it an admin or not.

Message ExternalUser

Show object example 
{
  "user_ids": {},
  "provider_ids": {},
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "external_id": "",
}

Fields:

Field user_ids
Type ttn.lorawan.v3. UserIdentifiers
Description

required
Field provider_ids
Type AuthenticationProviderIdentifiers
Description

required
Field created_at
Type google.protobuf. Timestamp
Field updated_at
Type google.protobuf. Timestamp
Field external_id
Type string
Description

max_len: 250

min_len: 1

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

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

Fields:

Field users
Type repeated User
Description

Message UserConsolePreferences

UserConsolePreferences is the message that defines the user preferences for the Console.

Show object example 
{
  "console_theme": "CONSOLE_THEME_SYSTEM",
  "dashboard_layouts": {},
  "sort_by": {},
  "tutorials": {},
}

Fields:

Field console_theme
Type ConsoleTheme
Field dashboard_layouts
Type UserConsolePreferences.DashboardLayouts
Field sort_by
Type UserConsolePreferences.SortBy
Field tutorials
Type UserConsolePreferences.Tutorials

Message UserConsolePreferences.DashboardLayouts

Show object example 
{
  "api_key": "DASHBOARD_LAYOUT_TABLE",
  "application": "DASHBOARD_LAYOUT_TABLE",
  "collaborator": "DASHBOARD_LAYOUT_TABLE",
  "end_device": "DASHBOARD_LAYOUT_TABLE",
  "gateway": "DASHBOARD_LAYOUT_TABLE",
  "organization": "DASHBOARD_LAYOUT_TABLE",
  "overview": "DASHBOARD_LAYOUT_TABLE",
  "user": "DASHBOARD_LAYOUT_TABLE",
}

Fields:

Field api_key
Type DashboardLayout
Field application
Type DashboardLayout
Field collaborator
Type DashboardLayout
Field end_device
Type DashboardLayout
Field gateway
Type DashboardLayout
Field organization
Type DashboardLayout
Field overview
Type DashboardLayout
Field user
Type DashboardLayout

Message UserConsolePreferences.SortBy

SortBy defines the field to which the Console will sort the display of entities.

Show object example 
{
  "api_key": "",
  "application": "",
  "collaborator": "",
  "end_device": "",
  "gateway": "",
  "organization": "",
  "user": "",
}

Fields:

Field api_key
Type string
Description

in: [ api_key_id -api_key_id name -name created_at -created_at expires_at -expires_at]
Field application
Type string
Description

in: [ application_id -application_id name -name created_at -created_at]
Field collaborator
Type string
Description

in: [ id -id rights -rights]
Field end_device
Type string
Description

in: [ device_id -device_id join_eui -join_eui dev_eui -dev_eui name -name description -description created_at -created_at last_seen_at -last_seen_at]
Field gateway
Type string
Description

in: [ gateway_id -gateway_id gateway_eui -gateway_eui name -name created_at -created_at]
Field organization
Type string
Description

in: [ organization_id -organization_id name -name created_at -created_at]
Field user
Type string
Description

in: [ user_id -user_id name -name primary_email_address -primary_email_address state -state admin -admin created_at -created_at]

Message UserConsolePreferences.Tutorials

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

Fields:

Field seen
Type repeated Tutorial
Description

unique

defined_only

Message UserSessionIdentifiers

Show object example 
{
  "user_ids": {},
  "session_id": "",
}

Fields:

Field user_ids
Type UserIdentifiers
Description

required
Field session_id
Type string
Description

max_len: 64

Enums

Enum ConsoleTheme

ConsoleTheme is the theme of the Console.

Name Value Description
CONSOLE_THEME_SYSTEM 0 The user prefers the system mode.
CONSOLE_THEME_LIGHT 1 The user prefers the light mode.
CONSOLE_THEME_DARK 2 The user prefers the dark mode.

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 DashboardLayout

DashboardLayout is a set of possible layout values to be used in the Console.

Name Value Description
DASHBOARD_LAYOUT_TABLE 0
DASHBOARD_LAYOUT_LIST 1
DASHBOARD_LAYOUT_GRID 2

Enum NotificationStatus

Name Value Description
NOTIFICATION_STATUS_UNSEEN 0
NOTIFICATION_STATUS_SEEN 1
NOTIFICATION_STATUS_ARCHIVED 2

Enum NotificationType

Name Value Description
UNKNOWN 0
API_KEY_CREATED 1
API_KEY_CHANGED 2
CLIENT_REQUESTED 3
COLLABORATOR_CHANGED 4
ENTITY_STATE_CHANGED 5
INVITATION 6
LOGIN_TOKEN 7
PASSWORD_CHANGED 8
TEMPORARY_PASSWORD 9
USER_REQUESTED 10
VALIDATE 11
SUPPORT_ACCESS_REQUESTED 12

Enum NotificationReceiver

Name Value Description
NOTIFICATION_RECEIVER_UNKNOWN 0
NOTIFICATION_RECEIVER_COLLABORATOR 1 Notification is received by collaborators of the entity. If the collaborator is an organization, the notification is received by organization members.
NOTIFICATION_RECEIVER_ADMINISTRATIVE_CONTACT 3 Notification is received by administrative contact of the entity. If this is an organization, the notification is received by organization members.
NOTIFICATION_RECEIVER_TECHNICAL_CONTACT 4 Notification is received by technical contact of the entity. If this is an organization, the notification is received by organization members.

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_LIST 87 The right to list users accounts.
RIGHT_USER_CREATE 88 The right to create an user account.
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_PURGE 66 The right to purge 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_PURGE 64 The right to purge 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_CLIENT_PURGE 68 The right to purge 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_PURGE 67 The right to purge 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_PURGE 65 The right to purge 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_ALERT_NOTIFICATION_PROFILE_CREATE 69 The right to create an alert notification profile.
RIGHT_ALERT_NOTIFICATION_PROFILE_INFO 70 The right to view an alert notification profile information.
RIGHT_ALERT_NOTIFICATION_PROFILE_LIST 71 The right to list the alert notification profiles.
RIGHT_ALERT_NOTIFICATION_PROFILE_UPDATE 72 The right to update an alert notification profiles.
RIGHT_ALERT_NOTIFICATION_PROFILE_DELETE 73 The right to delete an alert notification profiles.
RIGHT_ALERT_NOTIFICATION_RECEIVER_CREATE 74 The right to create an alert notification receiver.
RIGHT_ALERT_NOTIFICATION_RECEIVER_INFO 75 The right to view an alert notification receiver information.
RIGHT_ALERT_NOTIFICATION_RECEIVER_LIST 76 The right to list the alert notification receivers.
RIGHT_ALERT_NOTIFICATION_RECEIVER_UPDATE 77 The right to update an alert notification receivers.
RIGHT_ALERT_NOTIFICATION_RECEIVER_DELETE 78 The right to delete an alert notification receivers.
RIGHT_AUTHENTICATION_PROVIDER_CREATE 79 The right to create an authentication provider.
RIGHT_AUTHENTICATION_PROVIDER_INFO 80 The right to view an authentication provider information.
RIGHT_AUTHENTICATION_PROVIDER_LIST 81 The right to list the authentication providers
RIGHT_AUTHENTICATION_PROVIDER_UPDATE 82 The right to update an authentication providers.
RIGHT_AUTHENTICATION_PROVIDER_DELETE 83 The right to delete an authentication providers.
RIGHT_EXTERNAL_USER_CREATE 84 The right to create an external user.
RIGHT_EXTERNAL_USER_INFO 85 The right to view an external user’s information.
RIGHT_EXTERNAL_USER_DELETE 86 The right to delete an external user.
RIGHT_PACKET_BROKER_AGENT_READ 89 The right to read any information related to the PBA.
RIGHT_PACKET_BROKER_AGENT_WRITE 90 The right to perform operations in the PBA.
RIGHT_TENANT_CONFIGURATION_UPDATE 91 The right to update a tenant’s configuration.
RIGHT_LABEL_CREATE 92 The right to create a label.
RIGHT_LABEL_INFO 93 The right to view a label’s information.
RIGHT_LABELS_LIST 94 The right to list the labels.
RIGHT_LABEL_UPDATE 95 The right to update a label.
RIGHT_LABEL_DELETE 96 The right to delete a label.
RIGHT_LABEL_ASSIGN 97 The right to assign a label to an entity.
RIGHT_ALL 55 The pseudo-right for all (current and future) possible rights.

Enum State

State enum defines states that an entity can be in.

Name Value Description
STATE_REQUESTED 0 Denotes that the entity has been requested and is pending review by an admin.
STATE_APPROVED 1 Denotes that the entity has been reviewed and approved by an admin.
STATE_REJECTED 2 Denotes that the entity has been reviewed and rejected by an admin.
STATE_FLAGGED 3 Denotes that the entity has been flagged and is pending review by an admin.
STATE_SUSPENDED 4 Denotes that the entity has been reviewed and suspended by an admin.

Enum Tutorial

Tutorial is a set of possible tutorials in the Console.

Name Value Description
TUTORIAL_UNKNOWN 0
TUTORIAL_LIVE_DATA_SPLIT_VIEW 1
TUTORIAL_LORAWAN_STARTER_USER 2
← Tenant APIs