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

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 Schema Definition Section for explanation of specific fields. This section is dedicated to technical specification for the properties.

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

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

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 is in accordance to W3C standard for Achievement type

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 should be the same as the one in credentialPayload, allowing other platforms to grab your VC image

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

attachments

array

N

Y

[ { pdf: “….” , png: “….“ }, { … } ]

no standard for internal objects

PreviousIntegration GuideNextAppendix

Last updated