Integration Guide

Expected User Flow

This is the expected user flow for third party platforms looking to integrate OCAs into their ecosystem. At this moment, OCAs can only be issued to an OCID account, therefore it is important that the OCID Connect portion is set up on your platform before any issuance happens.

1. Requesting for an OC Developer Account

We have just launched the OC Developer portal hoping to scale up the capability of self-served integration for developers and partners. Head to https://auth.opencampus.xyz/login to create an OCID if you have not already done so.

Once you've done so, prepare the following information and head to https://developers.opencampus.xyz/login and apply for a developer account with your OCID. It will take typically 3-5 working days for review, alternatively you can reach out to @lewlian on telegram to expedite your approval if needed.

Onboarding form for developer account
Post application screen (pending approval)

2. Setting up your Open Campus ID (Sandbox)

A sandbox environment can be activated in the SDK for development purposes. Please find the full guide for Open Campus ID Connect integration here

When you have completed the integration on production, you should have a “Connect with OCID” that allows you to:

  • Create a new OCID

  • Login and connect an existing OCID

Before you move on to the next segment, it is recommended that you generate two OCID accounts:

  1. Issuer’s OCID: This is the OCID account that will be requesting for Issuer permission and also become the Issuing entity for OCAs later. This should be the OCID that already has access to the developer portal

  2. User’s OCID: This is the OCID account that will be receiving the OCA and view them on the OCID Dashboard.

2. Issuing Open Campus Achievements (Sandbox)

Update: You no longer require a sandbox OCID to test the staging endpoint. You can use your actual production OCID for both staging and production OCA testing. Make sure you have a valid OCID from https://auth.opencampus.xyz/login

On a high level, a Sandbox Issuer’s API Key will be needed to issue an OCA with the sandbox API endpoint provided. To obtain it, please head to https://developers.opencampus.xyz and login with the OCID account registered as a developer. Click on "OCA API Keys".

OC Developer Dashboard

Select "Request staging key" and allow a few minutes for your keys to be generated in the backend.

Before generating OCA Staging API Keys

Once your staging API keys are generated, you should be able to see the two parameters that you need for integration:

  • Staging API Key

  • DID String

After generating OCA Staging API Keys

Authorization

Once your obtained an API Key from the dashboard, you can use your API Key in the HTTP POST header for authorization:

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

Staging endpoint for OCA Issuance: 

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

Body Params (JSON)

If you have followed the guide, holderOcId will refer to the User’s OCID that you generated in the previous segment. If you only have one OCID generated you may also issue an OCA to the issuer’s account.

Sample Body (raw JSON):

{
	"credentialPayload": { ... },
	"holderOcId": "bob.edu"
}

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]](mailto:[email protected])",
        "image": "[https://img.freepik.com/premium-vector/gold-medal-with-gold-ribbon-that-says-gold_1134661-43944.jpg](https://img.freepik.com/premium-vector/gold-medal-with-gold-ribbon-that-says-gold_1134661-43944.jpg)",
        "profileUrl": "[https://mycourse.xyz/profile/johndoe](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

If you wish to find out more about the specifications for each of the properties in the body params, please refer to API Specifications. You will also find the recommended image dimensions for OCAs there.

OCID Dashboard

Once you have successfully issued the OCA to a holder’s OCID, there are two ways that you can view the OCA:

  1. Logging in to the Open Campus ID Dashboard in the sandbox environment using the holder’s account at https://id.sandbox.opencampus.xyz

  2. View the holder’s public profile at https://id.sandbox.opencampus.xyz/public/credentials?username=<OC_ID>

3. Preparing for Production

In order to ensure that third party integrations are successful and did not deviate too much from the intended flow of how OCAs should be issued, we require teams to do a recording of their integrated flow on the sandbox environment and submit to the Open Campus team via the form below. Please reach out to @kittyvo and @lewlian to escalate your review process.

To promote the sandbox environment to production, you will need:

  1. Request for Issuer’s production API Key

    1. Complete and submit this form to the Open Campus team

    2. Once this is approved, you will be informed and able to view your API Key and DID Key for production from the OC Developer Dashboard

    3. Then replace with the production issuance endpoint 

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

Secure your API Key safely, your API Key is tied to your issuer identity and losing your API Key means allowing others to issue Achievements on your behalf.

PreviousGetting StartedNextAPI Specifications

Last updated