Application APIs

The ApplicationRegistry service

Method ApplicationRegistry.Create
Description Create a new application. This also sets the given organization or user as first collaborator with all possible rights.
Request type CreateApplicationRequest
Response type Application
HTTP bindings

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

POST /api/v3/organizations/{collaborator.organization_ids.organization_id}/applications

Method ApplicationRegistry.Get
Description Get the application 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 GetApplicationRequest
Response type Application
HTTP bindings

GET /api/v3/applications/{application_ids.application_id}

Method ApplicationRegistry.List
Description List applications where the given user or organization is a direct collaborator. If no user or organization is given, this returns the applications 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 ListApplicationsRequest
Response type Applications
HTTP bindings

GET /api/v3/applications

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

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

Method ApplicationRegistry.Update
Description Update the application, changing the fields specified by the field mask to the provided values.
Request type UpdateApplicationRequest
Response type Application
HTTP bindings

PUT /api/v3/applications/{application.ids.application_id}

Method ApplicationRegistry.Delete
Description Delete the application. This may not release the application ID for reuse. All end devices must be deleted from the application before it can be deleted.
Request type ApplicationIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/applications/{application_id}

The EntityRegistrySearch service

Method EntityRegistrySearch.SearchApplications
Request type SearchEntitiesRequest
Response type Applications
HTTP bindings

GET /api/v3/search/applications

The ApplicationAccess service

Method ApplicationAccess.ListRights
Description List the rights the caller has on this application.
Request type ApplicationIdentifiers
Response type Rights
HTTP bindings

GET /api/v3/applications/{application_id}/rights

Method ApplicationAccess.CreateAPIKey
Description Create an API key scoped to this application.
Request type CreateApplicationAPIKeyRequest
Response type APIKey
HTTP bindings

POST /api/v3/applications/{application_ids.application_id}/api-keys

Method ApplicationAccess.ListAPIKeys
Description List the API keys for this application.
Request type ListApplicationAPIKeysRequest
Response type APIKeys
HTTP bindings

GET /api/v3/applications/{application_ids.application_id}/api-keys

Method ApplicationAccess.GetAPIKey
Description Get a single API key of this application.
Request type GetApplicationAPIKeyRequest
Response type APIKey
HTTP bindings

GET /api/v3/applications/{application_ids.application_id}/api-keys/{key_id}

Method ApplicationAccess.UpdateAPIKey
Description Update the rights of an API key of the application. 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 UpdateApplicationAPIKeyRequest
Response type APIKey
HTTP bindings

PUT /api/v3/applications/{application_ids.application_id}/api-keys/{api_key.id}

Method ApplicationAccess.GetCollaborator
Description Get the rights of a collaborator (member) of the application. Pseudo-rights in the response (such as the “_ALL” right) are not expanded.
Request type GetApplicationCollaboratorRequest
Response type GetCollaboratorResponse
HTTP bindings

/api/v3

GET /api/v3/applications/{application_ids.application_id}/collaborator/user/{collaborator.user_ids.user_id}

GET /api/v3/applications/{application_ids.application_id}/collaborator/organization/{collaborator.organization_ids.organization_id}

Method ApplicationAccess.SetCollaborator
Description Set the rights of a collaborator (member) on the application. 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 SetApplicationCollaboratorRequest
Response type google.protobuf.Empty
HTTP bindings

PUT /api/v3/applications/{application_ids.application_id}/collaborators

Method ApplicationAccess.ListCollaborators
Description List the collaborators on this application.
Request type ListApplicationCollaboratorsRequest
Response type Collaborators
HTTP bindings

GET /api/v3/applications/{application_ids.application_id}/collaborators

Messages

Message APIKey

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

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

Message APIKeys

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

Message Application

Application is the message that defines an Application in the network.

Field ids
Type ApplicationIdentifiers
Description

required

Field created_at
Type google.protobuf.Timestamp
Field updated_at
Type google.protobuf.Timestamp
Field name
Type string
Description

max_len: 50

Field description
Type string
Description

max_len: 2000

Field attributes
Type map of string to string
Description

Key-value attributes for this application. Typically used for organizing applications or for storing integration-specific data.

max_len (key): 36

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

Field contact_info
Type repeated ContactInfo
Description

Contact information for this application. Typically used to indicate who to contact with technical/security questions about the application.

Show object example
{
  "ids": {},
  "created_at": "0001-01-01T00:00:00Z",
  "updated_at": "0001-01-01T00:00:00Z",
  "name": "",
  "description": "",
  "attributes": {},
  "contact_info": [],
}

Message ApplicationIdentifiers

Field application_id
Type string
Description

max_len: 36

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

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

Message Applications

Field applications
Type repeated Application
Description
Show object example
{
  "applications": [],
}

Message Collaborator

Field ids
Type OrganizationOrUserIdentifiers
Description

required

Field rights
Type repeated Right
Description

defined_only

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

Message Collaborators

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

Message CreateApplicationAPIKeyRequest

Field application_ids
Type ApplicationIdentifiers
Description

required

Field name
Type string
Description

max_len: 50

Field rights
Type repeated Right
Description

defined_only

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

Message CreateApplicationRequest

Field application
Type Application
Description

required

Field collaborator
Type OrganizationOrUserIdentifiers
Description

Collaborator to grant all rights on the newly created application.

required

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

Message GetApplicationAPIKeyRequest

Field application_ids
Type ApplicationIdentifiers
Description

required

Field key_id
Type string
Description

Unique public identifier for the API key.

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

Message GetApplicationCollaboratorRequest

Field application_ids
Type ApplicationIdentifiers
Description

required

Field collaborator
Type OrganizationOrUserIdentifiers
Description

required

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

Message GetApplicationRequest

Field application_ids
Type ApplicationIdentifiers
Description

required

Field field_mask
Type google.protobuf.FieldMask
Description

The names of the application fields that should be returned.

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

Message GetCollaboratorResponse

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

Message ListApplicationAPIKeysRequest

Field application_ids
Type ApplicationIdentifiers
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.

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

Message ListApplicationCollaboratorsRequest

Field application_ids
Type ApplicationIdentifiers
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.

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

Message ListApplicationsRequest

Field collaborator
Type OrganizationOrUserIdentifiers
Description

By default we list all applications the caller has rights on. Set the user or the organization (not both) to instead list the applications where the user or organization is collaborator on.

Field field_mask
Type google.protobuf.FieldMask
Description

The names of the application 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: [ application_id -application_id name -name created_at -created_at]

Field limit
Type uint32
Description

Limit the number of results per page.

lte: 1000

Field page
Type uint32
Description

Page number for pagination. 0 is interpreted as 1.

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

Message OrganizationOrUserIdentifiers

OrganizationOrUserIdentifiers contains either organization or user identifiers.

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

Message Rights

Field rights
Type repeated Right
Description

defined_only

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

Message SearchEntitiesRequest

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

Field id_contains
Type string
Description

Find entities where the ID contains this substring.

Field name_contains
Type string
Description

Find entities where the name contains this substring.

Field description_contains
Type string
Description

Find entities where the description contains this substring.

Field attributes_contain
Type map of string to string
Description

Find entities where the given attributes contain these substrings.

max_len (key): 36

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

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.

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.

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

Message SetApplicationCollaboratorRequest

Field application_ids
Type ApplicationIdentifiers
Description

required

Field collaborator
Type Collaborator
Description

required

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

Message UpdateApplicationAPIKeyRequest

Field application_ids
Type ApplicationIdentifiers
Description

required

Field api_key
Type APIKey
Description

required

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

Message UpdateApplicationRequest

Field application
Type Application
Description

required

Field field_mask
Type google.protobuf.FieldMask
Description

The names of the application fields that should be updated.

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

Message UserIdentifiers

Field user_id
Type string
Description

This ID shares namespace with organization IDs.

max_len: 36

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

Field email
Type string
Description

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

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