# API Reference

{% hint style="info" %}
Please find the SDK [here](https://github.com/ontology-tech/onttag-sdk-js).
{% endhint %}

## Installation

You can start with importing the `@ont-dev/ont-tag` package by running npm command below.

You can now use the following `import` statement to bring in all the modules from the `@ont-dev/ont-tag` package.

```javascript
import VC from "@ont-dev/ont-tag";
```

The following `require` statement can also be used to load the modules.

```javascript
var VC = require("@ont-dev/ont-tag");
```

To use the methods in a browser, you must use the compiled version of the library. The `browser.js` file is located in the `lib` directory. You can include it in your project using a `script` tag as follows.

```javascript
<script src="./lib/browser.js"></script>
```

Everything will now be available under the `VC` variable. For instance, to fetch the list of available regions, you can invoke:

```javascript
var areaList = VC.utils.areaList;
```

## Usage

### Method list

| Method name                                                                                                                                                                  | Description                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [sendUserInfo](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#sending-an-authentication-request)          | Sends authentication request to the trust anchor service with user's KYC details |
| [getSocialAuthLink](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#fetch-third-party-authentication-link) | Fetch URL to initiate social media platform authentication                       |
| [getVcList](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#fetching-credentials)                          | Fetches any issued credentials for previously sent authentication requests       |
| [utils.areaList](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#utility-methods)                          | Returns a list of countries and regions with their respective aliases            |
| [utils.authType](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#authtype)                                 | Returns a list of valid authentication types                                     |
| [utils.chainType](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#chaintype)                               | Returns the list of supported chains                                             |
| [utils.generateId](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#generateid)                             | Generates a valid ONT ID using a wallet addresses                                |
| [utils.serializeSignMessage](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#serializesignmessage)         | Serializes the passed object data to generate a `base64` string                  |
| [utils.createPresentation](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#createpresentation)             | Generates a presentation for the passed credential data payload                  |
| [utils.deserialize](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#deserialize)                           | Deserializes the passed `base64` string to an object                             |

### Sending an Authentication Request

This method is used to send authentication requests for a user's KYC data. It takes two parameters. The first one is an object literal with the KYC info. as defined below, and the second one is your API key.

```javascript
params // parameters to be passed
{
  appId: string,    // Application ID, assigned by Ontology
  region: string,  // Nationality (area alias)
  docId: string,    // Document ID no.
  authType: string,  // Document or authentication type
  frontDoc: string, // Front page image of the selected document (encoded)
  backDoc: string,  // Last page image of the selected document (encoded)
  name: string,     // Legal name as in document
  ownerDid: string  // DID of the user, generated using the generateId utility method
}
```

> **Note:** Both the `frontDoc` and `backDoc` images need to be passed as `base64` encoded strings.

The `region` field takes the respective alias for each region. Use the [`areaList`](broken://pages/-MieUnVe6Pds40bRP_eE#arealist) utility method to obtain the list of countries and their aliases.

The `ownerDid` field takes an ONT ID. You can generate one using the [`generateId`](broken://pages/-MieUnVe6Pds40bRP_eE#generateid) utility method.

The `authType` field specifies the type of document sent for authentication. Use the [`authType`](broken://pages/-MieUnVe6Pds40bRP_eE#authtype) utility method to fetch the list of valid documents.

Call the method with the user info and your API key to send an authentication request.

```javascript
await VC.sendUserInfo({ ...params }, apiKey);
```

It returns `true` for a successful request and an error message if an exception occurs.

| Error Message            | Description                       |
| ------------------------ | --------------------------------- |
| SUCCESS                  | Authentication successful         |
| APP\_NOT\_FOUND          | Passed `appId` not found          |
| REQUEST\_LIMIT\_EXCEEDED | Request limit for a user exceeded |
| SIG\_VERIFY\_FAILED      | Invalid API signature             |
| INTERNAL\_ERROR          | Internal error occurred           |

> **Note:** Each application (identified with the combination of their appid and API key) is limited to sending 10 requests for a user's particular document/authentication method (identified with a user's DID context). Also, in case of an internal error, please get in touch with the Ontology team.

### Fetch Third Party Authentication Link

Invoking this method returns a URL that can be used to prompt user authentication for a social media platform.

```javascript
getSocialAuthLink(ownerDid, authType, apiKey, appId);
```

It takes four parameters.

* `ownerDid`: User's DID
* `authType`: The authentication method (social media platform). [See here](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#authtype)
* `apiKey`: Your API key
* `appId`: Your app ID

The method returns a URL that triggers OAuth authentication for a particular platform.

Once successfully authorized, a credential will be issued that can be used to prove the relationship between a social media account and a DID.

### Fetching Credentials

You can use this method to fetch the issued credentials for a user after having sent a data authentication request.

This method takes two parameters, the DID of the user (or owner in the context of a credential), and the ID document type.

```javascript
const result = await VC.getVcList(ownerDid, authType);
```

If the authentication was successful, the `encryptOriginData` field will contain serialized credential data.

```javascript
{
  authId: '0348xxxx-xxxx-4317-xxxx-8d6f6166a65b',
  appId: 'tesxxxx01',
  credentialContext: 'credential:sfp_passport_authentication',
  description: 'My Shuftipro Passport Authentication',
  txHash: '9494568336a4c2xxxxxxxxxxxxxxxxbaa066e1585fe47',
  status: 1,
  encryptOriginData: 'xxxxxxx', // credential information
  requestTime: 1622156645 // unix timestamp (in seconds)
}
```

| Status | Description               |
| ------ | ------------------------- |
| 1      | Authentication successful |
| 2      | Authentication failed     |
| 0      | Verification in progress  |

> **Note:** The user needs to sign this data to authorize access and prove their relationship with the credential data. After fetching the credential data, you can proceed with generating a presentation with the signed credential data as its payload. The resultant token can then be used for signature verification and access control.

### Utility Methods

`utils` class contains multiple methods that can be used to perform specific tasks. Each method is described below.

#### **`areaList`**

Invoking this method returns an array of all the supported countries and regions with their respective aliases.

The response is structured as follows.

```javascript
[
  { name: 'Afghanistan', alias: 'AF' },
  { name: 'Aland Islands', alias: 'AX' },
  ...
]
```

#### **`authType`**

This method returns the list of supported documents and authentication types as an object.

The response is of the following form.

```javascript
{
  Passport: 'passport',
  IdCard: 'id_card',
  DrivingLicense: 'driving_license',
  Twitter: 'twitter',
  Github: 'github',
  Linkedin: 'linkedin',
  Line: 'line',
  Amazon: 'amazon',
  Kakao: 'kakao'
}
```

#### **`chainType`**

This method returns an object containing valid chain type names.

The response is as follows.

```javascript
{
  ETH: 'etho',
  BSC: 'bnb'
}
```

#### **`generateId`**

Invoking this method with a wallet address prefixes it with the appropriate DID method based on the passed `chainType` and returns a valid ONT ID as a string. For e.g., `did:etho:0xdc6...974a9`.

```javascript
const ownerDid = VC.utils.generateId("0xdc6...974a9", chainType);
```

#### **`serializeSignMessage`**

This method returns a serialized `base64` JWT string. It takes the following parameters:

1. `jwtStr` - The credential JWT string
2. `audienceId` - DID of the credential consumer
3. `ownerDid` - DID of the Credential owner
4. `effectiveTime` - Validity period of the presentation (in seconds). For e.g., 1 day = 86400

The parameters are of the following form.

```javascript
{
  jwtStr: string,
  audienceId: string,
  ownerDid: string,
  effectiveTime: number   // Presentation Effective time, eg 1 day = 86400
}
```

```javascript
const JWT = VC.utils.serializeSignMessage(params);
```

#### **`createPresentation`**

Invoke this method to generate a presentation with credential data signed by the user. It returns the presentation as a JWT string.

It takes an object parameter containing:

1. `signMessage` - Serialized JWT string (using [`serializeSignMessage`](broken://pages/-MieUnVe6Pds40bRP_eE#serializesignmessage))
2. `signature` - Serialized JWT string that has been signed by the user

The parameter object is of the following form.

```javascript
{
  signMessage: string,
  signature: string
}
```

```
const JWT = VC.utils.createPresentation(params);
```

Presentation data can be obtained by deserializing this token. You can perform signature verification and message decryption using the Java SDK. Follow this [link](https://github.com/ontology-tech/onttag-sdk-js/blob/master) for reference.

#### **`deserialize`**

You can obtain the user's verified KYC data by deserializing the `encryptOriginData` string in the credential object received [here](/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.md#fetching-credentials).

This method takes the serialized JWT string as parameter and returns an object containing credential data.

```javascript
const result = VC.utils.deserialize(string);
```

The response object is of the following form.

```javascript
{
  '@context': [
    'https://www.w3.org/20xxxxxxxxxxxx',
    'https://ontid.ont.i20xxxxxxxxxxxx',
    'credential:sfp_passport_authentication'
  ],
  id: 'urn:uuid:861cbae4-xxxx-4844-xxxx-8c8xxxx7052',
  type: [ 'VerifiableCredential' ],
  issuer: 'did:ont:APc8FBxxxxxxxxxxxxxxSUFX2HAnBuBna',
  issuanceDate: '2021-05-28T07:04:23.000Z',
  expirationDate: '2022-05-28T07:04:23.000Z',
  credentialStatus: {
    id: '4f7f159ac4xxxxxxxxxxx5f61b7d0cc6',
    type: 'AttestContract'
  },
  credentialSubject: {
    Name: 'xxxxxxxx',
    BirthDay: 'xxxx-03-09',
    ExpirationDate: 'xxxx-03-12',
    IDDocNumber: 'xx26xxxx86',
    IssuerName: 'Shxxxxro',
    user_did: 'did:ont:5cxxxxxxxx701CbBExxxxx29b'
  },
  proof: {
    type: 'JWT',
    verificationMethod: 'did:ont:APcxxxxxxxxq2BSUFX2xxxxxna#keys-1',
    created: '2021-05-28T07:04:23Z',
    proofPurpose: 'assertionMethod',
    jws: 'ARyjxxxxxxxxxxxxxxxxxxGDisGMJdFE/4erXIazh3n8ipPotTFA+Z4hS09GlhVaio=\\'
  }
}
```


---

# 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://docs.ont.io/decentralized-identity-and-data/ontid/ont-tag/verification-via-did-verifiable-credentials-service-integration.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.