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

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

Field Type Description
ids ApplicationIdentifiers

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

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

contact_info repeated ContactInfo

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 Type Description
application_id string

max_len: 36

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

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

Message Applications

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

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 CreateApplicationAPIKeyRequest

Field Type Description
application_ids ApplicationIdentifiers

required

name string

max_len: 50

rights repeated Right

defined_only

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

Message CreateApplicationRequest

Field Type Description
application Application

required

collaborator OrganizationOrUserIdentifiers

Collaborator to grant all rights on the newly created application.

required

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

Message GetApplicationAPIKeyRequest

Field Type Description
application_ids ApplicationIdentifiers

required

key_id string

Unique public identifier for the API key.

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

Message GetApplicationCollaboratorRequest

Field Type Description
application_ids ApplicationIdentifiers

required

collaborator OrganizationOrUserIdentifiers

required

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

Message GetApplicationRequest

Field Type Description
application_ids ApplicationIdentifiers

required

field_mask google.protobuf.FieldMask

The names of the application fields that should be returned.

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

Message GetCollaboratorResponse

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

Message ListApplicationAPIKeysRequest

Field Type Description
application_ids ApplicationIdentifiers

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
{
  "application_ids": {},
  "limit": 0,
  "page": 0,
}

Message ListApplicationCollaboratorsRequest

Field Type Description
application_ids ApplicationIdentifiers

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
{
  "application_ids": {},
  "limit": 0,
  "page": 0,
}

Message ListApplicationsRequest

Field Type Description
collaborator OrganizationOrUserIdentifiers

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_mask google.protobuf.FieldMask

The names of the application fields that should be returned.

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: [ application_id -application_id 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 SetApplicationCollaboratorRequest

Field Type Description
application_ids ApplicationIdentifiers

required

collaborator Collaborator

required

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

Message UpdateApplicationAPIKeyRequest

Field Type Description
application_ids ApplicationIdentifiers

required

api_key APIKey

required

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

Message UpdateApplicationRequest

Field Type Description
application Application

required

field_mask google.protobuf.FieldMask

The names of the application fields that should be updated.

Show object example
{
  "application": {},
  "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": "",
}