API Specifications

Staging (Sandbox) OCA/OCB Issuance Endpoint:

POST <https://api.vc.staging.opencampus.xyz/issuer/vc>

Production OCA/OCB Issuance Endpoint

POST <https://api.vc.opencampus.xyz/issuer/vc>

Authorization

Header: {  X-API-KEY: <your api key> }

Body for OCA (raw JSON)

{
	"credentialPayload": { ... },
	"holderOcId": "bob.edu",
	"issuerReferenceId": "tt:1111222333"
}

name	type	example
credentialPayload	object	{ "validFrom": "2023-12-10T16:00:00.000Z", "awardedDate": "2023-12-10T16:00:00.000Z", "description": "An achievement for achieving outstanding results in mathematics course", "credentialSubject": { "name": "John Doe", "type": "Person", "email": "[email protected]", "image": "https://img.freepik.com/premium-vector/gold-medal-with-gold-ribbon-that-says-gold_1134661-43944.jpg", "profileUrl": "https://mycourse.xyz/profile/johndoe", "achievement": { "name": "Gold Medal Achievements", "identifier": "tt:1111222333", "description": "Reached 200 points in the intermediate mathematics", "achievementType": "Achievement", "attachments": [ { "url": "<URL_OF_ATTACHMENT>", "type": "<ENUM_ATTACHMENT_TYPE>", "title": "<NAME_OF_ATTACHMENT>" } ] }, "ext:OC_CUSTOM:custom": { "ext:OC_CUSTOM:<OC_ID_OF_ISSUER>:key1": "custom value 1", "ext:OC_CUSTOM:<OC_ID_OF_ISSUER>:key2": "custom value 2" } } }
holderOcId	string	bob.edu

Body for OCB (raw JSON)

{
	"credentialPayload": { ... },
	"collectionSymbol": "ocbadge",
	"holderOcId": "bob.edu" OR "holderAddress": "0xabcD12345...",
	"issuerReferenceId": "tt:1111222333"
}

name	type	example
credentialPayload	object	{ "validFrom": "2023-12-10T16:00:00.000Z", "awardedDate": "2023-12-10T16:00:00.000Z", "description": "Season 3 Badge from XXXSwap", "credentialSubject": { "type": "Person", "image": "https://img.freepik.com/premium-vector/gold-medal-with-gold-ribbon-that-says-gold_1134661-43944.jpg", "profileUrl": "https://mycourse.xyz/profile/johndoe", "achievement": { "name": "LiquidityKing", "identifier": "tt:1111222333", "description": "transacting more than $100 in value on Sailfish", "achievementType": "Badge" }, } }

About issuerReferenceId

Issuer reference ID is an optional field that is used to uniquely identify the OCA/OCB issued by the issuer. Each issuer reference ID can be only used once by each issuer. Issuance will fail if there is another OCA/OCB with the same issuer reference ID that has been issued by the same issuer before.

More on Credential Payload

Credential Payload is what you would use to represent the credential that you are issuing. We accept the following fields. Some of them are required and some of them are optional. Here we list the specifications for the credential payload based on the OpenBadge standard.

Please refer to the tables below for the explanation of specific fields, including examples how the metadata of Open Campus's verifiable credential should be structured.

More on Images

There are 2 locations where you should provide your image URI when issuing your credentials. The image in credentialSubject follows the guideline of W3C standard for Achievement type of verifiable credential. The image in credentialPayload allows other platforms (NFT Marketplaces, Block explorers, etc.) to grab your VC image.

credentialPayload

Property Name	Data Type	Required	Public	Example	Remark
awardedDate	string	Y	Y	2023-09-08T16:00:00.000Z	ISO 8601 Date Format
description	string	Y	Y	my school certification	Description of the credential
validFrom	string	Y	Y	2023-09-08T16:00:00.000Z	ISO 8601 Date Format
validUntil	string	N	Y	2023-09-08T16:00:00.000Z	ISO 8601 Date Format
image	string	N	Y	https://image.com/img/11111.jpg	Valid http uri. This should be the same as the one in credentialPayload, allowing other platforms to grab your VC image
credentialSubject	object	Y	Y	{ … }	see below details

credentialSubject

Property Name	Data Type	Required	Public	Example	Remark
achievement	object	Y	Y	{ … }	see below details
name	string	Y	N	Bob	stored but not exposed to public
email	string	Y	N	[email protected]	stored but not exposed to public
profileUrl	string	N	Y	https://mycompany.xyz/profiles/public/11223344	this should be users public profile
image	string	N	Y	https://image.com/img/11111.jpg	Valid http uri, this is in accordance to W3C standard for Achievement type
ext:OC_CUSTOM:custom	object	N	Y	{ … }	unspecified blob of custom data

achievement

Property Name	Data Type	Required	Public	Example	Remark
identifier	string	Y	Y	a8505caa-8e3a-4c07-aae2-94944c6b52fc	stored on-chain maxLength 50 characters
achievementType	string	Y	Y	Certificate	see appendix for valid achievement types
name	string	Y	Y	Blockchain Certification
description	string	Y	Y	An introductory blockchain bootcamp class	description of the achievement requirement
attachments	array	N	Y	[ { pdf: “….” , png: “….“ }, { … } ]	no standard for internal objects