Platform API v2 Documentation

Table of Contents

• platformapiv2.proto

  • AgentsStruct
  • ConfigureAgentReq
  • ConfigureAgentRes
  • CreateUserReq
  • CreateUserRes
  • DeleteUserReq
  • DeleteUserRes
  • DownloadReleaseZipReq
  • DownloadReleaseZipRes
  • DownloadReq
  • DownloadRes
  • GetAgentInfoReq
  • GetAgentInfoRes
  • GetAgentsListReq
  • GetAgentsListRes
  • GetAppLogsReq
  • GetAppLogsRes
  • GetAppOnboardingInfoReq
  • GetAppOnboardingInfoRes
  • GetIDSettingsReq
  • GetIDSettingsRes
  • GetIdentityInfoReq
  • GetIdentityInfoRes
  • GetIdentityLogReq
  • GetIdentityLogRes
  • GetIntegrationConfigReq
  • GetIntegrationConfigRes
  • GetReleasesReq
  • GetReleasesRes
  • GetUserInfoReq
  • GetUserInfoRes
  • GetUsersReq
  • GetUsersRes
  • InviteUserReq
  • InviteUserRes
  • RecordAppLogsReq
  • RecordAppLogsRes
  • RegisterAgentReq
  • RegisterAgentRes
  • RequestRegistrationCodeReq
  • RequestRegistrationCodeRes
  • ResetPasswordReq
  • ResetPasswordRes
  • RevokeAgentReq
  • RevokeAgentRes
  • ScuridAppOnboardingInfo
  • SetIDSettingsReq
  • SetIDSettingsRes
  • StoreAppOnboardingInfoReq
  • StoreAppOnboardingInfoRes
  • StoreIntegrationConfigReq
  • StoreIntegrationConfigRes
  • UpdateUserPasswordReq
  • UpdateUserPasswordRes
  • VerifyAgentReq

  • VerifyAgentRes

  • Platform

  • Subsystems

• Scalar Value Types

Top

platformapiv2.proto

AgentsStruct

Field	Type	Label	Description
agentVersion	string		version of the Scurid Edge Agent
requestedOn	int64		date on which Scurid backend received agent's req for reg.
deviceContext	deviceContext.DeviceContext		DeviceContext from the hardware on which the agent is running
SignatureOnDeviceContext	bytes		hashed value generated on structure DeviceContext + Requested on + ApprovedOn. THIS is also used as the key which will be delivered to
status	string		current status of the Agent, refer to models/v1/status.go
name	string		alias defined for the agent by the user, if none create one for the user
revokedOn	int64		RevokedOn timestamp for agent's identity revocation
devices	string	repeated	this is the list of identities linked to this agent
approvedOn	int64		Unix time stamp on which agent's approved. If client does not provide this, server timestamp will be attached.
agentIdentity	string		agent's identity
platformIdentity	string		platform's identity
approvalKey	bytes		post approval this key is returned to the agent for reference DeviceContext + Requested on + ApprovedOn + Agent's DID. THIS is also used as the key which will be delivered to
verifiedOn	int64		Unix timestamp for verification
integrationDetails	integration.IntegrationDetails		default is nil, if agent is configured with any integration, this will be populated
signatureOnIntegration	signature.Signature		signature of the Scurid Server's identity on the integration details. This is used to verify the integrity of the integration details.
storageSchemaMetadata	storageSchemaMetadata.StoreSchemaMetadataRequest		default is nil, if agent is configured with any storage schema, this will be populated
storageTableName	string

ConfigureAgentReq

Field	Type	Label	Description
agentID	string		AgentID is the DID of the agent to be configured
integrationDetails	integration.IntegrationDetails		IntegrationDetails is the configuration to be applied to the agent
agentAlias	string		agentAlias custom alias for the agent
storeSchemaMetadataRequest	storageSchemaMetadata.StoreSchemaMetadataRequest		defines the storage schema structure applied to the agent data storage
storageTableName	string		defines the storage table name for the agent data storage this will be used for creating the database table name; in reference to the RDBMS storage structure

ConfigureAgentRes

Field	Type	Label	Description
status	bool		Status is the status of the configuration operation

CreateUserReq

Field	Type	Label	Description
user	user.v1.User
userData	user.v1.UserData
inviteKey	string		this is the key that will be used to invite the user, and would have been sent to the user when sending the invite.

CreateUserRes

Field	Type	Label	Description
result	bool

DeleteUserReq

Field	Type	Label	Description
email	string

DeleteUserRes

Field	Type	Label	Description
result	bool

DownloadReleaseZipReq

Field	Type	Label	Description
version	string

DownloadReleaseZipRes

Field	Type	Label	Description
file	release.CompleteReleaseZip

DownloadReq

Field	Type	Label	Description
asset	release.Asset	repeated

DownloadRes

Field	Type	Label	Description
version	release.DownloadVersion

GetAgentInfoReq

Field	Type	Label	Description
agentId	string		agent's DID information

GetAgentInfoRes

Field	Type	Label	Description
agentInfo	AgentsStruct		uses defined AgentsStruct

GetAgentsListReq

GetAgentsListReq

intentionally left empty

GetAgentsListRes

Field	Type	Label	Description
list	AgentsStruct	repeated	array of all the agents along with their details

GetAppLogsReq

Field	Type	Label	Description
range	log.LogRange

GetAppLogsRes

Field	Type	Label	Description
log	log.AppLog		returns log structure

GetAppOnboardingInfoReq

Field	Type	Label	Description
platformIdentity	string

GetAppOnboardingInfoRes

Field	Type	Label	Description
onboardingInfo	ScuridAppOnboardingInfo

GetIDSettingsReq

left empty intentionally

GetIDSettingsRes

Field	Type	Label	Description
autoApproveDeviceID	bool		if enabled, new incoming device identities (which usually end up in pending) belonging to existing approved and valid agents will be automatically approved; default is false

GetIdentityInfoReq

request message for GetIdentityInfo

Field	Type	Label	Description
did	string		identity in the format did:scurid:<publicKey>

GetIdentityInfoRes

response message for GetIdentityInfo

Field	Type	Label	Description
vInfo	string		edge agent version used for creating DID
lastVerifiedOn	int64		Unix timestamp when an identity was last verified with the SSI Service
createdOn	int64		Unix timestamp when identity was created
rejectedOn	int64		Unix timestamp when identity was rejected
deviceName	string		alias name for the device, defined by the user or system
isLocal	bool		if checked identities are not registered on DLT but only local database
path	string		device pkg file store for staging client files
tags	string	repeated	provides list of tags attached the identity
pendingSince	int64		Unix timestamp since identity has been pending for action
deviceContext	deviceContext.DeviceContext		helps to onboard and bind a device to an identity

GetIdentityLogReq

Field	Type	Label	Description
range	log.LogRange

GetIdentityLogRes

Field	Type	Label	Description
log	log.IdentityLog

GetIntegrationConfigReq

left empty

GetIntegrationConfigRes

Field	Type	Label	Description
thingworx	integration.ThingWorx
hawkbit	integration.Hawkbit
azure	integration.Azure

GetReleasesReq

Field	Type	Label	Description
timestamp	google.protobuf.Timestamp		use this to filter the releases; field is optional
version	google.protobuf.StringValue		use this to filter the releases; if not provided, field is optional

GetReleasesRes

Field	Type	Label	Description
list	release.ReleaseStruct	repeated

GetUserInfoReq

Field	Type	Label	Description
email	string

GetUserInfoRes

Field	Type	Label	Description
userData	user.v1.UserData
userOperation	user.v1.UserOperation
role	user.v1.Role
inviteKey	string		this is the key that will be used to invite the user, and would have been sent to the user when sending the invite.

GetUsersReq

left empty

GetUsersRes

Field	Type	Label	Description
usersList	string	repeated

InviteUserReq

Field	Type	Label	Description
userInvite	user.v1.UserInvite

InviteUserRes

Field	Type	Label	Description
result	bool

RecordAppLogsReq

Field	Type	Label	Description
log	log.AppLog		app log structure

RecordAppLogsRes

Field	Type	Label	Description
res	bool

RegisterAgentReq

Field	Type	Label	Description
agentDID	string		this is the identity of the agent, auto generated
platformDID	string		this is the platform's identity generated once during user onboarding
name	string		optional, an alias for the agent
approvedOn	int64		Unix timestamp, if client won't send any server will assign current timestamp

RegisterAgentRes

Field	Type	Label	Description
result	bool		true if operation is successful, else false along with error if any

RequestRegistrationCodeReq

Field	Type	Label	Description
email	string

RequestRegistrationCodeRes

Field	Type	Label	Description
result	bool		if a valid email was received server will send a code and return here true; else false

ResetPasswordReq

Field	Type	Label	Description
email	string

ResetPasswordRes

Field	Type	Label	Description
result	bool		if a valid email was received server will send a code and return here true; else false

RevokeAgentReq

Field	Type	Label	Description
agentDID	string		this is the identity of the agent, auto generated
platformDID	string		this is the platform's identity generated once during user onboarding
name	string		optional, an alias for the agent
revokedOn	int64		Unix timestamp, if client won't send any server will assign current timestamp

RevokeAgentRes

Field	Type	Label	Description
result	bool		true if operation is successful, else false along with error if any

ScuridAppOnboardingInfo

Field	Type	Label	Description
onboardingInfo	string		this must be a json formatted string

SetIDSettingsReq

Field	Type	Label	Description
autoApproveDeviceID	bool		if enabled, new incoming device identities (which usually end up in pending) belonging to existing approved and valid agents will be automatically approved; default is false

SetIDSettingsRes

SetIDSettingsRes is the response from the backend

Field	Type	Label	Description
result	bool		returns true if successful

StoreAppOnboardingInfoReq

Field	Type	Label	Description
platformIdentity	string
onboardingInfo	ScuridAppOnboardingInfo

StoreAppOnboardingInfoRes

Field	Type	Label	Description
result	bool

StoreIntegrationConfigReq

StoreIntegrationConfigReq send one or all config at once

Field	Type	Label	Description
thingworx	integration.ThingWorx
hawkbit	integration.Hawkbit
azure	integration.Azure

StoreIntegrationConfigRes

Field	Type	Label	Description
result	bool		default is false, if successful returns True

UpdateUserPasswordReq

Field	Type	Label	Description
email	string
code	string
newPassword	bytes

UpdateUserPasswordRes

Field	Type	Label	Description
result	bool		if user was updated successfully return true; else false

VerifyAgentReq

Field	Type	Label	Description
agentDID	string		this is the identity of the agent, auto generated
platformDID	string		this is the platform's identity generated once during user onboarding

VerifyAgentRes

Field	Type	Label	Description
result	bool		true if status is still approved , else false along with error if any

Platform

Method Name	Request Type	Response Type	Description
GetIdentityInfo	GetIdentityInfoReq	GetIdentityInfoRes	Fetches details available on a given identity in local DB storage it can be used for any kind of identity i.e.approved, rejected or pending GetIdentityInfo is currently under development do not use //
GetAgentsList	GetAgentsListReq	GetAgentsListRes	GetAgentsList returns list of all agents along with their details
GetAgentInfo	GetAgentInfoReq	GetAgentInfoRes	GetAgentInfo returns detail about individual agent identity
RegisterAgent	RegisterAgentReq	RegisterAgentRes	RegisterAgent approves a pending agent in the system
RevokeAgent	RevokeAgentReq	RevokeAgentRes	RevokeAgent revokes an agent's identity
VerifyAgent	VerifyAgentReq	VerifyAgentRes	VerifyAgent verifies agent's authenticity against the Scurid SSI service
ConfigureAgent	ConfigureAgentReq	ConfigureAgentRes	ConfigureAgent helps modify Scurid Edge Agent behaviour

Subsystems

Provides configuration possibilities for different components in the system

Method Name	Request Type	Response Type	Description
GetIDSettings	GetIDSettingsReq	GetIDSettingsRes	GetIDSettings gets currently stored settings about IDs
SetIDSettings	SetIDSettingsReq	SetIDSettingsRes	SetIDSettings sets up different settings
GetIdentityLog	GetIdentityLogReq	GetIdentityLogRes stream	GetIdentityLog provides list of log recorded on activities performed on identities. This covers both agent and non agent identities.
RecordAppLogs	RecordAppLogsReq	RecordAppLogsRes	RecordAppLogs records Scurid App logs
GetAppLogs	GetAppLogsReq	GetAppLogsRes stream	GetAppLogs fetches app log persisted as history
StoreIntegrationConfig	StoreIntegrationConfigReq	StoreIntegrationConfigRes	Stores Integration configuration in Scurid Server storage This is a global configuration and will be used by all identities
GetIntegrationConfig	GetIntegrationConfigReq	GetIntegrationConfigRes	GetIntegrationConfig fetches currently stored integration configuration from Scurid Server This is a global configuration and will be used by all identities
StoreAppOnboardingInfo	StoreAppOnboardingInfoReq	StoreAppOnboardingInfoRes	Stores the user onboarding information created
GetAppOnboardingInfo	GetAppOnboardingInfoReq	GetAppOnboardingInfoRes	Fetches the user onboarding information created
CreateUser	CreateUserReq	CreateUserRes	Creates a new App User in the Scurid Server
InviteUser	InviteUserReq	InviteUserRes	Sends invite to a new user
GetUsers	GetUsersReq	GetUsersRes	GetUsers returns list of users
DeleteUser	DeleteUserReq	DeleteUserRes	DeleteUser deletes a user
GetUserInfo	GetUserInfoReq	GetUserInfoRes	GetUserInfo returns user info
ResetPassword	ResetPasswordReq	ResetPasswordRes	Resets the password of a user
UpdateUserPassword	UpdateUserPasswordReq	UpdateUserPasswordRes	UpdateUserPassword updates the user
GetReleases	GetReleasesReq	GetReleasesRes	Get versions list
Download	DownloadReq	DownloadRes stream	Called by clients to Download file(s)
DownloadReleaseZip	DownloadReleaseZipReq	DownloadReleaseZipRes stream	Request to download a zip file, containing all the files in the release from Edge Agent, Server & App etc. Request only need the version number
RequestRegistrationCode	RequestRegistrationCodeReq	RequestRegistrationCodeRes	RequestRegistrationCode generates a registration code for the user Call this API if the code which user has, has already expire or is invalid

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)