# 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.

<figure><img src="/files/ZSBbys0GbbYcnm42eFJb" alt=""><figcaption></figcaption></figure>

## 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. If you are building on behalf of an organisation, we strongly recommend that you create a separate OCID \<organisationName>.edu that will be used to request for production API key.

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.

<figure><img src="/files/OjwfoGYGZRqwzzGguSsx" alt=""><figcaption><p>Onboarding form for developer account</p></figcaption></figure>

<figure><img src="/files/XMsiHUt8ZoLEWxDAhgQg" alt=""><figcaption><p>Post application screen (pending approval)</p></figcaption></figure>

## 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](/start-building/open-campus-id-connect-sdk.md)

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/Badges (Sandbox)

{% hint style="info" %}
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>
{% endhint %}

On a high level, a Sandbox Issuer’s API Key will be needed to issue an OCA/OCB 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". <br>

<figure><img src="/files/xjqFG9NNxmdVjaexJPtP" alt=""><figcaption><p>OC Developer Dashboard</p></figcaption></figure>

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

<figure><img src="/files/KgQqVmZr1KP6gJwj1PjC" alt=""><figcaption><p>Before generating OCA Staging API Keys</p></figcaption></figure>

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**

<figure><img src="/files/phHrEVrKxEKrAd6Zebct" alt=""><figcaption><p>After generating OCA Staging API Keys</p></figcaption></figure>

**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> }
```

### **a. Staging endpoint for OCA Issuance:**&#x20;

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

**Body Params (JSON)**

If you have followed the [guide](#id-1.-setting-up-your-open-campus-id-sandbox), *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):

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

<table><thead><tr><th>name</th><th>type</th><th>example</th></tr></thead><tbody><tr><td><strong>credentialPayload</strong></td><td>object</td><td><pre class="language-json"><code class="lang-json">{"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": "johndoe@something.edu",
        "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"
        }
    }
}
</code></pre></td></tr><tr><td><strong>holderOcId</strong></td><td>string</td><td>bob.edu</td></tr></tbody></table>

<mark style="color:red;">If you wish to find out more about the specifications for each of the properties in the body params, please refer to</mark> [<mark style="color:red;">API Specifications</mark>](/start-building/open-campus-achievements-badges/api-specifications.md)<mark style="color:red;">. You will also find the recommended image dimensions for OCAs there.</mark>

**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>

### b. Staging endpoint for OCB Issuance

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

**Body Params (JSON)**

For OC Badges, it is largely similar to OC Achievements but you will need to specify *collectionSymbol* as *ocbadge* otherwise it will default to OCA issuance. You may also issue OC Badges directly to wallets instead of OCIDs by changing *holderOcId* to *holderAddress*

Sample Body for issuance to OCID (raw JSON):

```json
{
    "credentialPayload": { ... },
    "collectionSymbol": "ocbadge",
    "holderOcId": "bob.edu"
}
```

Sample Body for issuance to wallet (raw JSON):

> :warning: <mark style="color:red;">For Yuzu x OC Badge Season 3 participating Dapps. Only OC badges issued to wallets are eligible for Yuzu points, please ensure that you are following the body params below for</mark> <mark style="color:red;"></mark><mark style="color:red;">**issuance to wallet**</mark><mark style="color:red;">.</mark>&#x20;

```json
{
    "credentialPayload": { ... },
    "collectionSymbol": "ocbadge",
    "holderAddress": "0xabcD12345..."
```

**CredentialPayload**

<table><thead><tr><th>name</th><th>type</th><th>example</th></tr></thead><tbody><tr><td><strong>credentialPayload</strong></td><td>object</td><td><pre class="language-json"><code class="lang-json">{
    "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"
		    },
}
</code></pre></td></tr></tbody></table>

<mark style="color:red;">For Yuzu x OC Badge Season 3 participating Dapps. Please ensure that</mark> <mark style="color:red;"></mark>*<mark style="color:red;">**name**</mark>* <mark style="color:red;"></mark><mark style="color:red;">in credentialPayload matches the</mark> <mark style="color:red;"></mark><mark style="color:red;">**Badge Name**</mark> <mark style="color:red;"></mark><mark style="color:red;">in your badge submission form</mark>&#x20;

## 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. &#x20;Complete and submit this [form](https://forms.gle/NyPk1MomUYRQcsD1A) 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
      1\.

      ```
      <figure><img src="/files/j5xnTCmhwLW7xZ7Wq1yt" alt=""><figcaption></figcaption></figure>
      ```
   3. Then replace with the production issuance endpoint&#x20;

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

<mark style="color:red;">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.</mark>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devdocs.educhain.xyz/start-building/open-campus-achievements-badges/integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.