Skip to main content

Protocol Documentation

Top

authn.proto

NOTE: This API is only exposed when the D1 service is configured to use the standalone ID provider.

AddUserToGroupsRequest

Represents the addition of a user to one or more groups.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

FieldTypeLabelDescription
user_idstringID of the user to add.
group_idsstringrepeatedIDs of the groups the user should be added to.

AddUserToGroupsResponse

Represents the result of a user addition to groups.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

CreateGroupRequest

Represents creation of a new group.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

FieldTypeLabelDescription
scopesd1.scopes.ScoperepeatedThe scopes the group should be assigned.

CreateGroupResponse

Represents the result of a group creation.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

FieldTypeLabelDescription
group_idstringID of the new group.

CreateUserRequest

Represents creation of a new user.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

FieldTypeLabelDescription
scopesd1.scopes.ScoperepeatedThe scopes the user should be assigned.

CreateUserResponse

Represents the result of a user creation.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

FieldTypeLabelDescription
user_idstringID of the new user.
passwordstringThe users password.

LoginUserRequest

Represents the user login.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

FieldTypeLabelDescription
user_idstringID of the user.
passwordstringThe users password.

LoginUserResponse

Represents the result of a user login.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

FieldTypeLabelDescription
access_tokenstringAccess token to be used in subsequent requests.
expiry_timeint64The expiration time of the access token.

RemoveUserFromGroupsRequest

Represents the removal of a user from one or more groups.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

FieldTypeLabelDescription
user_idstringID of the user to remove.
group_idsstringrepeatedIDs of the groups the user should be removed from.

RemoveUserFromGroupsResponse

Represents the result of a user removal from groups.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

RemoveUserRequest

Represents the removal of a user.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

FieldTypeLabelDescription
user_idstringID of the user to remove.

RemoveUserResponse

Represents the result of a user removal.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Authn

Service for user management.

NOTE: This API is only exposed when the D1 service is configured to use the standalone ID provider.

Method NameRequest TypeResponse TypeDescription
CreateUserCreateUserRequestCreateUserResponseCreates a new user. This call can fail if the auth storage cannot be reached, in which case an error is returned.
LoginUserLoginUserRequestLoginUserResponseLogs in an existing user, returning a User Access Token and an expiry time. This call can fail if the caller provides the wrong credentials or if the auth storage cannot be reached, in which case an error is returned.
RemoveUserRemoveUserRequestRemoveUserResponseDeletes an existing user. This call can fail if the user does not exist, or if the auth storage cannot be reached, in which case an error is returned.
CreateGroupCreateGroupRequestCreateGroupResponseCreates a new group with the requested scopes. The caller is added to the group. This call can fail if the auth storage cannot be reached, in which case an error is returned.
AddUserToGroupsAddUserToGroupsRequestAddUserToGroupsResponseAdds a user to one or more groups. This call can fail if the auth storage cannot be reached, in which case an error is returned.
RemoveUserFromGroupsRemoveUserFromGroupsRequestRemoveUserFromGroupsResponseRemoves a user from one or more groups. This call can fail if the auth storage cannot be reached, in which case an error is returned.

Top

authz.proto

AddPermissionRequest

Represents a request to add permission to an object.

FieldTypeLabelDescription
object_idstringThe ID of the object to add the permission to.
group_idsstringrepeatedThe IDs of the groups to give access.

AddPermissionResponse

Represents the result of a request to add permission to an object.

CheckPermissionRequest

Represents a request to check whether the user has permission to an object.

FieldTypeLabelDescription
object_idstringThe ID of the object to check permission for.

CheckPermissionResponse

Represents the result of a request to check whether a user has permission to an object.

FieldTypeLabelDescription
has_permissionboolIndicates whether the caller has access to the object.

GetPermissionsRequest

Represents a request to get the permissions of an object.

FieldTypeLabelDescription
object_idstringThe ID of the object to get the permission list for.

GetPermissionsResponse

Represents the result of a request to get permissions for an object.

FieldTypeLabelDescription
group_idsstringrepeatedList of groups with access to the object.

RemovePermissionRequest

Represents a request to remove permission to an object.

FieldTypeLabelDescription
object_idstringThe ID of the object to remove the permission for.
group_idsstringrepeatedThe IDs of the groups to revoke permission for.

RemovePermissionResponse

Represents the result of a request to remove permission to an object.

Authz

Service for managing authorization rules.

Method NameRequest TypeResponse TypeDescription
GetPermissionsGetPermissionsRequestGetPermissionsResponseReturns a list of groups with access to the specified object. This call can fail if the auth storage cannot be reached, in which case an error is returned. The calling user has to be authenticated and authorized to access the object in order to get the object permissions. Requires the scope GETACCESS.
AddPermissionAddPermissionRequestAddPermissionResponseAdds one or more groups to the access list of the specified object. This call can fail if the caller does not have access to the object, if the target group does not exist, or if the auth storage cannot be reached. In these cases, an error is returned. Requires the scope MODIFYACCESS.
RemovePermissionRemovePermissionRequestRemovePermissionResponseRemoves one or more groups from the access list of the specified object. This call can fail if the caller does not have access to the object or if the auth storage cannot reached. In these cases, an error is returned. Requires the scope MODIFYACCESS.
CheckPermissionCheckPermissionRequestCheckPermissionResponseChecks whether the caller has access to the specified object. This call can fail if the auth storage cannot be reached. In this cases, an error is returned. Requires the scope GETACCESS.

Top

generic.proto

DecryptRequest

Represents a request to decrypt data.

FieldTypeLabelDescription
ciphertextbytesData to decrypt.
associated_databytesAssociated data.
object_idstringThe object ID of the data.

DecryptResponse

Represents a response to a decryption request.

FieldTypeLabelDescription
plaintextbytesDecrypted data.
associated_databytesAssociated data.

EncryptRequest

Represents a request to encrypt data.

FieldTypeLabelDescription
plaintextbytesData to encrypt.
associated_databytesAssociated data.
group_idsstringrepeatedOptional additional groups to add to the access list.

EncryptResponse

Represents a response to an encryption request.

FieldTypeLabelDescription
ciphertextbytesCiphertext of the provided plaintext.
associated_databytesAssociated data.
object_idstringThe object ID of the encrypted data.

Generic

Service for encryption and decryption of data.

Method NameRequest TypeResponse TypeDescription
EncryptEncryptRequestEncryptResponseEncrypts data and returns the ciphertext without storing it.
DecryptDecryptRequestDecryptResponseAuthorizes the user for access permissions and if accessible, returns the decrypted content.

Top

index.proto

AddRequest

Represents a request to add keywords/identifier pairs.

FieldTypeLabelDescription
keywordsstringrepeatedKeywords to be associated with identifier in secure index.
identifierstringIdentifier, e.g. a document ID, to be stored in secure index.

AddResponse

Represents a response to an add request.

DeleteRequest

Represents a request to delete keywords/identifier pairs from secure index.

FieldTypeLabelDescription
keywordsstringrepeatedKeywords that are associated with identifier in secure index.
identifierstringIdentifier stored in secure index.

DeleteResponse

Represents a response to a delete request.

SearchRequest

Represents a request to search for a keyword in secure index.

FieldTypeLabelDescription
keywordstringKeyword to search for in secure index.

SearchResponse

Represents a response to a search request.

FieldTypeLabelDescription
identifiersstringrepeatedIdentifiers that contain the keyword in secure index.

Index

Service for using secure index.

Method NameRequest TypeResponse TypeDescription
AddAddRequestAddResponseAdds keywords/identifier pairs to secure index.
SearchSearchRequestSearchResponseSearches in secure index.
DeleteDeleteRequestDeleteResponseDeletes keywords/identifier pairs from secure index.

Top

scopes.proto

Scope

Access scopes.

NameNumberDescription
READ0Read and decrypt data.
CREATE1Store and encrypt data.
GETACCESS2Get permissions to an object.
MODIFYACCESS3Modify permissions to an object.
UPDATE4Modify data.
DELETE5Delete data.
INDEX6Use secure index for searching in data.

Top

version.proto

VersionRequest

Represents a request to get version information.

VersionResponse

Represents a response to get version information.

FieldTypeLabelDescription
commitstringThe Git commit of the running service.
tagstringThe version of the running service.

Version

Service for getting version information.

Method NameRequest TypeResponse TypeDescription
VersionVersionRequestVersionResponseReturns the versions of the currently running service.

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
doubledoubledoublefloatfloat64doublefloatFloat
floatfloatfloatfloatfloat32floatfloatFloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intintint32intintegerBignum or Fixnum (as required)
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/longint64longinteger/stringBignum
uint32Uses variable-length encoding.uint32intint/longuint32uintintegerBignum or Fixnum (as required)
uint64Uses variable-length encoding.uint64longint/longuint64ulonginteger/stringBignum or Fixnum (as required)
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intintint32intintegerBignum or Fixnum (as required)
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/longint64longinteger/stringBignum
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intintuint32uintintegerBignum or Fixnum (as required)
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/longuint64ulonginteger/stringBignum
sfixed32Always four bytes.int32intintint32intintegerBignum or Fixnum (as required)
sfixed64Always eight bytes.int64longint/longint64longinteger/stringBignum
boolboolbooleanbooleanboolboolbooleanTrueClass/FalseClass
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicodestringstringstringString (UTF-8)
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr[]byteByteStringstringString (ASCII-8BIT)