Organization APIs

The OrganizationRegistry service

Method OrganizationRegistry.Create
Description Create a new organization. This also sets the given user as first collaborator with all possible rights.
Request type CreateOrganizationRequest
Response type Organization
HTTP bindings

POST /api/v3/users/{collaborator.user_ids.user_id}/organizations
Method OrganizationRegistry.Get
Description Get the organization 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 GetOrganizationRequest
Response type Organization
HTTP bindings

GET /api/v3/organizations/{organization_ids.organization_id}
Method OrganizationRegistry.List
Description List organizations where the given user or organization is a direct collaborator. If no user or organization is given, this returns the organizations 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 ListOrganizationsRequest
Response type Organizations
HTTP bindings

GET /api/v3/organizations

GET /api/v3/users/{collaborator.user_ids.user_id}/organizations
Method OrganizationRegistry.Update
Description Update the organization, changing the fields specified by the field mask to the provided values.
Request type UpdateOrganizationRequest
Response type Organization
HTTP bindings

PUT /api/v3/organizations/{organization.ids.organization_id}
Method OrganizationRegistry.Delete
Description Delete the organization. This may not release the organization ID for reuse.
Request type OrganizationIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/organizations/{organization_id}
Method OrganizationRegistry.Restore
Description

Restore a recently deleted organization.

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

POST /api/v3/organizations/{organization_id}/restore
Method OrganizationRegistry.Purge
Description Purge the organization. This will release the organization 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 OrganizationIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/organizations/{organization_id}/purge

The EntityRegistrySearch service

Method EntityRegistrySearch.SearchOrganizations
Description Search for organizations that match the conditions specified in the request. Non-admin users will only match organizations that they have rights on.
Request type SearchOrganizationsRequest
Response type Organizations
HTTP bindings

GET /api/v3/search/organizations

The OrganizationAccess service

Method OrganizationAccess.ListRights
Description List the rights the caller has on this organization.
Request type OrganizationIdentifiers
Response type Rights
HTTP bindings

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

POST /api/v3/organizations/{organization_ids.organization_id}/api-keys
Method OrganizationAccess.DeleteAPIKey
Description Delete a single API key of this organization.
Request type DeleteOrganizationAPIKeyRequest
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/organizations/{organization_ids.organization_id}/api-keys/{key_id}
Method OrganizationAccess.ListAPIKeys
Description List the API keys for this organization.
Request type ListOrganizationAPIKeysRequest
Response type APIKeys
HTTP bindings

GET /api/v3/organizations/{organization_ids.organization_id}/api-keys
Method OrganizationAccess.GetAPIKey
Description Get a single API key of this organization.
Request type GetOrganizationAPIKeyRequest
Response type APIKey
HTTP bindings

GET /api/v3/organizations/{organization_ids.organization_id}/api-keys/{key_id}
Method OrganizationAccess.UpdateAPIKey
Description Update the rights of an API key of the organization. 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 UpdateOrganizationAPIKeyRequest
Response type APIKey
HTTP bindings

PUT /api/v3/organizations/{organization_ids.organization_id}/api-keys/{api_key.id}
Method OrganizationAccess.GetCollaborator
Description Get the rights of a collaborator (member) of the organization. Pseudo-rights in the response (such as the “_ALL” right) are not expanded.
Request type GetOrganizationCollaboratorRequest
Response type GetCollaboratorResponse
HTTP bindings

/api/v3

GET /api/v3/organizations/{organization_ids.organization_id}/collaborator/user/{collaborator.user_ids.user_id}
Method OrganizationAccess.DeleteCollaborator
Description DeleteCollaborator removes a collaborator from an organization.
Request type DeleteOrganizationCollaboratorRequest
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/organizations/{organization_ids.organization_id}/collaborators/user/{collaborator_ids.user_ids.user_id}
Method OrganizationAccess.SetCollaborator
Description Set the rights of a collaborator (member) on the organization. Organization collaborators can get access to the organization itself, as well as any application, gateway and OAuth client this organization is a collaborator of. 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 SetOrganizationCollaboratorRequest
Response type google.protobuf.Empty
HTTP bindings

PUT /api/v3/organizations/{organization_ids.organization_id}/collaborators
Method OrganizationAccess.ListCollaborators
Description List the collaborators on this organization.
Request type ListOrganizationCollaboratorsRequest
Response type Collaborators
HTTP bindings

GET /api/v3/organizations/{organization_ids.organization_id}/collaborators

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

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
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 CreateOrganizationRequest

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

Fields:

Field organization
Type Organization
Description

required
Field collaborator
Type OrganizationOrUserIdentifiers
Description

Collaborator to grant all rights on the newly created application. NOTE: It is currently not possible to have organizations collaborating on other organizations.

required

Message DeleteOrganizationAPIKeyRequest

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field key_id
Type string

Message DeleteOrganizationCollaboratorRequest

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field collaborator_ids
Type OrganizationOrUserIdentifiers
Description

required

Message GetCollaboratorResponse

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

Fields:

Field ids
Type OrganizationOrUserIdentifiers
Field rights
Type repeated Right
Description

Message GetOrganizationAPIKeyRequest

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field key_id
Type string
Description

Unique public identifier for the API key.

Message GetOrganizationCollaboratorRequest

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field collaborator
Type OrganizationOrUserIdentifiers
Description

NOTE: It is currently not possible to have organizations collaborating on other organizations.

required

Message GetOrganizationRequest

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the organization fields that should be returned.

Message ListOrganizationAPIKeysRequest

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
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 ListOrganizationCollaboratorsRequest

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
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 ListOrganizationsRequest

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

Fields:

Field collaborator
Type OrganizationOrUserIdentifiers
Description

By default we list all organizations the caller has rights on. Set the user to instead list the organizations where the user or organization is collaborator on. NOTE: It is currently not possible to have organizations collaborating on other organizations.
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the organization 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: [ organization_id -organization_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.
Field deleted
Type bool
Description

Only return recently deleted organizations.

Message Organization

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": {},
  "application_limit": null,
  "client_limit": null,
  "gateway_limit": null,
}

Fields:

Field ids
Type OrganizationIdentifiers
Description

The identifiers of the organization. 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 organization 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 organization 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 organization 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 organization. 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 organization.

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

Key-value attributes for this organization. Typically used for organizing organizations 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 organization. Typically used to indicate who to contact with security/billing questions about the organization. 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 application_limit
Type google.protobuf. UInt64Value
Description

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

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

The maximum number of gateways of the organization. This field can only be modified by admins.

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

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

Fields:

Field organizations
Type repeated Organization
Description

Message Rights

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

Fields:

Field rights
Type repeated Right
Description

defined_only

Message SearchOrganizationsRequest

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

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

Fields:

Field query
Type string
Description

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

max_len: 50
Field id_contains
Type string
Description

Find organizations where the ID contains this substring.

max_len: 50
Field name_contains
Type string
Description

Find organizations where the name contains this substring.

max_len: 50
Field description_contains
Type string
Description

Find organizations where the description contains this substring.

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

Find organizations 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 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: [ organization_id -organization_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.
Field deleted
Type bool
Description

Only return recently deleted organizations.

Message SetOrganizationCollaboratorRequest

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
Description

required
Field collaborator
Type Collaborator
Description

required

Message UpdateOrganizationAPIKeyRequest

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

Fields:

Field organization_ids
Type OrganizationIdentifiers
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 UpdateOrganizationRequest

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

Fields:

Field organization
Type Organization
Description

required
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the organization 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.

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 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.
← Network Server APIs Packet Broker APIs →