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}

The EntityRegistrySearch service

Method EntityRegistrySearch.SearchUsers
Request type SearchEntitiesRequest
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.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}

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

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 CreateUserAPIKeyRequest

Field Type Description
user_ids UserIdentifiers

required

name string

max_len: 50

rights repeated Right

defined_only

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

Message CreateUserRequest

Field Type Description
user User

required

invitation_token string

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

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

Message DeleteInvitationRequest

Field Type Description
email string

email

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

Message GetUserAPIKeyRequest

Field Type Description
user_ids UserIdentifiers

required

key_id string

Unique public identifier for the API key.

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

Message GetUserRequest

Field Type Description
user_ids UserIdentifiers

required

field_mask google.protobuf.FieldMask

The names of the user fields that should be returned.

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

Message Invitation

Field Type Description
email string

email

token string
expires_at google.protobuf.Timestamp
created_at google.protobuf.Timestamp
updated_at google.protobuf.Timestamp
accepted_at google.protobuf.Timestamp
accepted_by UserIdentifiers
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": {},
}

Message Invitations

Field Type Description
invitations repeated Invitation
Show object example
{
  "invitations": [],
}

Message ListInvitationsRequest

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

Message ListUserAPIKeysRequest

Field Type Description
user_ids UserIdentifiers

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

Message ListUsersRequest

Field Type Description
field_mask google.protobuf.FieldMask

The names of the user 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: [ user_id -user_id name -name primary_email_address -primary_email_address state -state admin -admin 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
{
  "field_mask": {},
  "order": "",
  "limit": 0,
  "page": 0,
}

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 SendInvitationRequest

Field Type Description
email string

email

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

Message UpdateUserAPIKeyRequest

Field Type Description
user_ids UserIdentifiers

required

api_key APIKey

required

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

Message UpdateUserRequest

Field Type Description
user User

required

field_mask google.protobuf.FieldMask

The names of the user fields that should be updated.

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

Message User

User is the message that defines a user on the network.

Field Type Description
ids UserIdentifiers

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 users. Typically used for storing integration-specific data.

contact_info repeated ContactInfo

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

primary_email_address string

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

email

primary_email_address_validated_at google.protobuf.Timestamp

When the primary email address was validated. Note that email address validation is not required on all networks.

password string

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.

password_updated_at google.protobuf.Timestamp
require_password_update bool
state State

The reviewing state of the user. This field can only be modified by admins.

defined_only

admin bool

This user is an admin. This field can only be modified by other admins.

temporary_password string

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.

temporary_password_created_at google.protobuf.Timestamp
temporary_password_expires_at google.protobuf.Timestamp
profile_picture Picture
Show object example
{
  "ids": {},
  "created_at": "0001-01-01T00:00:00Z",
  "updated_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",
  "admin": false,
  "temporary_password": "",
  "temporary_password_created_at": "0001-01-01T00:00:00Z",
  "temporary_password_expires_at": "0001-01-01T00:00:00Z",
  "profile_picture": {},
}

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": "",
}

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": "",
}

Message Users

Field Type Description
users repeated User
Show object example
{
  "users": [],
}