Client APIs

List of Client APIs.

The ClientRegistry service

Method ClientRegistry.Create
Description Create a new OAuth client. This also sets the given organization or user as first collaborator with all possible rights.
Request type CreateClientRequest
Response type Client
HTTP bindings

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

POST /api/v3/organizations/{collaborator.organization_ids.organization_id}/clients
Method ClientRegistry.Get
Description Get the OAuth client 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 GetClientRequest
Response type Client
HTTP bindings

GET /api/v3/clients/{client_ids.client_id}
Method ClientRegistry.List
Description List OAuth clients where the given user or organization is a direct collaborator. If no user or organization is given, this returns the OAuth clients the caller has access to. Similar to Get, this selects the fields specified in the field mask. More or less fields may be returned, depending on the rights of the caller.
Request type ListClientsRequest
Response type Clients
HTTP bindings

GET /api/v3/clients

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

GET /api/v3/organizations/{collaborator.organization_ids.organization_id}/clients
Method ClientRegistry.Update
Description Update the OAuth client, changing the fields specified by the field mask to the provided values.
Request type UpdateClientRequest
Response type Client
HTTP bindings

PUT /api/v3/clients/{client.ids.client_id}
Method ClientRegistry.Delete
Description Delete the OAuth client. This may not release the client ID for reuse.
Request type ClientIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/clients/{client_id}
Method ClientRegistry.Restore
Description

Restore a recently deleted client.

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

POST /api/v3/clients/{client_id}/restore
Method ClientRegistry.Purge
Description Purge the client. This will release the client ID for reuse.
Request type ClientIdentifiers
Response type google.protobuf.Empty
HTTP bindings

DELETE /api/v3/clients/{client_id}/purge

The ClientAccess service

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

GET /api/v3/clients/{client_id}/rights
Method ClientAccess.GetCollaborator
Description Get the rights of a collaborator (member) of the client. Pseudo-rights in the response (such as the “_ALL” right) are not expanded.
Request type GetClientCollaboratorRequest
Response type GetCollaboratorResponse
HTTP bindings

/api/v3

GET /api/v3/clients/{client_ids.client_id}/collaborator/user/{collaborator.user_ids.user_id}

GET /api/v3/clients/{client_ids.client_id}/collaborator/organization/{collaborator.organization_ids.organization_id}
Method ClientAccess.DeleteCollaborator
Description DeleteCollaborator removes a collaborator from a client.
Request type DeleteClientCollaboratorRequest
Response type google.protobuf.Empty
HTTP bindings

/api/v3

DELETE /api/v3/clients/{client_ids.client_id}/collaborators/user/{collaborator_ids.user_ids.user_id}

DELETE /api/v3/clients/{client_ids.client_id}/collaborators/organization/{collaborator_ids.organization_ids.organization_id}
Method ClientAccess.SetCollaborator
Description Set the rights of a collaborator (member) on the OAuth client. 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 SetClientCollaboratorRequest
Response type google.protobuf.Empty
HTTP bindings

PUT /api/v3/clients/{client_ids.client_id}/collaborators
Method ClientAccess.ListCollaborators
Description List the collaborators on this OAuth client.
Request type ListClientCollaboratorsRequest
Response type Collaborators
HTTP bindings

GET /api/v3/clients/{client_ids.client_id}/collaborators

The EntityRegistrySearch service

Method EntityRegistrySearch.SearchClients
Description Search for OAuth clients that match the conditions specified in the request. Non-admin users will only match OAuth clients that they have rights on.
Request type SearchClientsRequest
Response type Clients
HTTP bindings

GET /api/v3/search/clients

Messages

Message Client

An OAuth client 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": [],
  "administrative_contact": {},
  "technical_contact": {},
  "secret": "",
  "redirect_uris": [],
  "logout_redirect_uris": [],
  "state": "STATE_REQUESTED",
  "state_description": "",
  "skip_authorization": false,
  "endorsed": false,
  "grants": [],
  "rights": [],
}

Fields:

Field ids
Type ClientIdentifiers
Description

The identifiers of the OAuth client. 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 OAuth client 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 OAuth client 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 OAuth client 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 OAuth client. 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 OAuth client. 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 client. Typically used for organizing clients 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 client. Typically used to indicate who to contact with technical/security questions about the application. This information is public and can be seen by any authenticated user in the network. 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 secret
Type string
Description

The client secret is only visible to collaborators of the client.

max_len: 128
Field redirect_uris
Type repeated string
Description

The allowed redirect URIs against which authorization requests are checked. If the authorization request does not pass a redirect URI, the first one from this list is taken. This information is public and can be seen by any authenticated user in the network.

max_items: 10

max_len: 128
Field logout_redirect_uris
Type repeated string
Description

The allowed logout redirect URIs against which client initiated logout requests are checked. If the authorization request does not pass a redirect URI, the first one from this list is taken. This information is public and can be seen by any authenticated user in the network.

max_items: 10

max_len: 128
Field state
Type State
Description

The reviewing state of the client. This information is public and can be seen by any authenticated user in the network. This field can only be modified by admins. If state_description is not updated when updating state, state_description is cleared.

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

If set, the authorization page will be skipped. This information is public and can be seen by any authenticated user in the network. This field can only be modified by admins.
Field endorsed
Type bool
Description

If set, the authorization page will show endorsement. This information is public and can be seen by any authenticated user in the network. This field can only be modified by admins.
Field grants
Type repeated GrantType
Description

OAuth flows that can be used for the client to get a token. This information is public and can be seen by any authenticated user in the network. After a client is created, this field can only be modified by admins.

defined_only
Field rights
Type repeated Right
Description

Rights denotes what rights the client will have access to. This information is public and can be seen by any authenticated user in the network. Users that previously authorized this client will have to re-authorize the client after rights are added to this list.

defined_only

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 CreateClientRequest

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

Fields:

Field client
Type Client
Description

required
Field collaborator
Type OrganizationOrUserIdentifiers
Description

Collaborator to grant all rights on the newly created client.

required

Message Collaborator

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

Fields:

Field ids
Type OrganizationOrUserIdentifiers
Description

required
Field rights
Type repeated Right
Description

defined_only

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 DeleteClientCollaboratorRequest

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

Fields:

Field client_ids
Type ClientIdentifiers
Description

required
Field collaborator_ids
Type OrganizationOrUserIdentifiers
Description

required

Message GetClientCollaboratorRequest

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

Fields:

Field client_ids
Type ClientIdentifiers
Description

required
Field collaborator
Type OrganizationOrUserIdentifiers
Description

required

Message GetClientRequest

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

Fields:

Field client_ids
Type ClientIdentifiers
Description

required
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the client fields that should be returned.

Message ListClientsRequest

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

Fields:

Field collaborator
Type OrganizationOrUserIdentifiers
Description

By default we list all OAuth clients the caller has rights on. Set the user or the organization (not both) to instead list the OAuth clients where the user or organization is collaborator on.
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the client 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: [ client_id -client_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 clients.

Message ListClientCollaboratorsRequest

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

Fields:

Field client_ids
Type ClientIdentifiers
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 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 SearchClientsRequest

This message is used for finding OAuth clients 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 OAuth clients where the ID, name or description contains this substring.

max_len: 50
Field id_contains
Type string
Description

Find OAuth clients where the ID contains this substring.

max_len: 50
Field name_contains
Type string
Description

Find OAuth clients where the name contains this substring.

max_len: 50
Field description_contains
Type string
Description

Find OAuth clients where the description contains this substring.

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

Find OAuth clients 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 OAuth clients 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: [ client_id -client_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 OAuth clients.

Message SetClientCollaboratorRequest

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

Fields:

Field client_ids
Type ClientIdentifiers
Description

required
Field collaborator
Type Collaborator
Description

required

Message UpdateClientRequest

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

Fields:

Field client
Type Client
Description

required
Field field_mask
Type google.protobuf. FieldMask
Description

The names of the client 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 ContactMethod

Name Value Description
CONTACT_METHOD_OTHER 0
CONTACT_METHOD_EMAIL 1
CONTACT_METHOD_PHONE 2

Enum ContactType

Name Value Description
CONTACT_TYPE_OTHER 0
CONTACT_TYPE_ABUSE 1
CONTACT_TYPE_BILLING 2
CONTACT_TYPE_TECHNICAL 3

Enum GrantType

The OAuth2 flows an OAuth client can use to get an access token.

Name Value Description
GRANT_AUTHORIZATION_CODE 0 Grant type used to exchange an authorization code for an access token.
GRANT_PASSWORD 1 Grant type used to exchange a user ID and password for an access token.
GRANT_REFRESH_TOKEN 2 Grant type used to exchange a refresh token for an access token.

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 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.
← Application Webhook APIs Crypto Operations APIs →