Platform APIv2 Documentation

Table of Contents

• deviceContext.proto

  • DeviceContext
  • MacAddress
  • OsInfo

• log.proto

  • AppLog
  • IdentityLog
  • LogRange

• platformapiv2.proto

  • AgentsStruct
  • GetAgentInfoReq
  • GetAgentInfoRes
  • GetAgentsListReq
  • GetAgentsListRes
  • GetAppLogsReq
  • GetAppLogsRes
  • GetIDSettingsReq
  • GetIDSettingsRes
  • GetIdentityInfoReq
  • GetIdentityInfoRes
  • GetIdentityLogReq
  • GetIdentityLogRes
  • RecordAppLogsReq
  • RecordAppLogsRes
  • RegisterAgentReq
  • RegisterAgentRes
  • RevokeAgentReq
  • RevokeAgentRes
  • SetIDSettingsReq
  • SetIDSettingsRes
  • VerifyAgentReq

  • VerifyAgentRes

  • ScuridServerV2

  • Subsystems

• Scalar Value Types

Top

deviceContext.proto

DeviceContext

Device context from the device in relation to the device identity

Field	Type	Label	Description
macAddresses	MacAddress	repeated	optional, all MAC addresses available to be picked up by the agent
ipAddress	string		optional, IP address
cpu	string		optional, number of CPUs available
ram	string		optional, RAM size on the device
imeiNumber	string		optional, International Mobile Equipment Identity, optional, capture if one is available
osType	OsInfo

MacAddress

list of macAddresses from the devices

Field	Type	Label	Description
mtu	int32		optional, maximum transmission unit
macAddress	string		optional
name	string		interface's name e.g. en0

OsInfo

OsInfo message structure defining standard OS info used within the system

Field	Type	Label	Description
osType	string		optional, e.g. darwin, windows, etc.
arch	string		optional, e.g. amd64 etc.

Top

log.proto

AppLog

Field	Type	Label	Description
type	string		INFO, WARN, DEBUG, TRACE, ERROR
message	string		string value of the message
eventTime	int64		UNIX NANO timestamp

IdentityLog

Field	Type	Label	Description
action	string		e.g. approved, revoked, pending or rejected.
eventTimestamp	int64		recorded timestamp of the event
signature	string		tamper evident signature on the
platformDID	string		user who performed the action - currently this is going to be the Platform DID
did	string		identity for device or agents

LogRange

Field	Type	Label	Description
from	int64		start timestamp
to	int64		stop timestamp

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

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

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

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

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

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

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

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

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)