# Provider API

{% hint style="info" %}
Each API contains at least 3 parts: `Description`, `Params`, `Return`, for the verification of several API (e.g. `did_login`, `did_requestCredentialDigest`, `did_requestCredentialContent`, `did_sign`) we provide the **Verification Method** in the [SDK](https://github.com/zCloak-Network/zkid-login/tree/master/packages/verify) respectively.
{% endhint %}

## All Methods

* [Provider API](https://docs.zkid.app/api/provider_api)
  * [All Methods](#all-methods)
    * [Authorization Method](#authorization-method)
      * [requestAuth( )](#requestauth)
      * [isAuth( )](#isauth)
    * [DID Request Method](#did-request-method)
      * [getCurrentDid( )](#getcurrentdid)
      * [did\_login(param)](#did_login-param)
      * [requestAuthAndLogin(param)](#requestauthandlogin-param)
    * [VC Request Method](#vc-request-method)
      * [requestCredentialDigest(params)](#requestcredentialdigest-params)
      * [requestCredentialContent(params)](#requestcredentialcontent-params)
    * [DID-Key Method](#did-key-method)
      * [sign(param)](#sign-param)
      * [encrypt(params)](#encrypt-params)
      * [decrypt(params)](#decrypt-params)
    * [ZKP Method](#zkp-method)
      * [generateZkp(params)](#generatezkp-params)

### Authorization Method

#### requestAuth( )

```typescript
public requestAuth(): Promise<boolean> {
    return this.request('wallet_requestAuth', undefined);
}
```

**Description**

This API is designed for websites to request authorization from Users. User permission is the *premise* of all interaction, if the website hasn't obtained User permission yet, it can not be able to use the following API to interact with the User.&#x20;

If this API returns Error Code `-32001`, it means that the User rejects this request.

**Return**

* `Boolean` - whether the User request for authorization is successfully allowed.

***

#### isAuth( )

```typescript
public isAuth(): Promise<boolean> {
    return this.request('wallet_isAuth', undefined);
}
```

**Description**

This API's return shows whether the authorization is allowed. It is used for developer to query the user's authorization permission status. If the query status is `true`, developer can continue to call other APIs. Otherwise, developer must first call `wallet_requestAuth()` to get permission.

**Return**

* `Boolean` - whether the user allows authorization already.

***

####

### DID Request Method

#### getCurrentDid( )

```typescript
public getCurrentDid(): Promise<RequestRpcs<'did_getCurrent'>['did_getCurrent'][1]> {
    return this.request('did_getCurrent', undefined);
  }
```

**Description**

As mentioned before, DID is the unique identifier of an entity. This API aims to fetch the current `didUri` in the zkID Wallet, which helps developers to identify each User.

**Return**

* `DidInfo` Object - an example is shown below:

```typescript
export type DidInfo = {
  didUri: DidUrl;
  document: DidDocument;
  authenticationKey: HexString;
  encryptionKey: HexString[];
  attestationKey?: HexString;
  delegationKey?: HexString;
};
```

***

#### did\_login(param)

```typescript
  public didLogin(
    data: HexString | Uint8Array | string | number
  ): Promise<RequestRpcs<'did_login'>['did_login'][1]> {
    const payload: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('did_login', { payload });
  }
```

**Description**

This API is for users to login the website with their DID. With this API, the user needs to make a signature on some message (given by the website) via the user's DID `AuthenticationKey`. Once the user has successfully signed, the API returns the result of the user's signature, and developers can verify the validity of the signature through the *Verify Method* in our SDK. If the verification passes, then the login request should be permitted.

If this API returns Error Code `-32001`, it means that the User rejects this request.

**Param:**

* data (required)

```json
// data is the one to be signed
param: [{
    "data": "0x....."
}]
```

**Return:**

* `HexString` - the user's signature on that data

**Usage Of Return**

After receiving the `HexString` signature, developers need to verify its validity in order to check user's identity. In the SDK, we offer this [verifyDidLogin function](https://docs.zkid.app/introduction/method#verifydidlogin) to help achieve that.

#### requestAuthAndLogin(param)

```typescript
  public requestAuthAndLogin(
    data: HexString | Uint8Array | string | number
  ): Promise<RequestRpcs<'wallet_requestAuthAndLogin'>['wallet_requestAuthAndLogin'][1]> {
    const payload: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('wallet_requestAuthAndLogin', { payload });
  }

```

**Description**

This API is used to request authorization from Users, and ask the User to sign on some specific data to achieve `DID Login`. You can see this API as the combination of [`requestAuth`](#requestauth) and [`did_login`](#did_login-param).&#x20;

If the User hasn't give an authorization to the website, this function will request for the authorization first, and then do [did\_login](#did_login-param).

If the User already give an authorization to the website, then this function does the same thing as [`did_login`](#did_login-param).

If this API returns Error Code `-32001`, it means that the User rejects this request.

**Param:**

* data (required)

```json
// data is the one to be signed
param: [{
    "data": "0x....."
}]
```

**Return:**

* `HexString` - the user's signature on that data

**Usage Of Return**

After receiving the `HexString` signature, developers need to verify its validity in order to check user's identity. In the SDK, we offer this [verifyDidLogin function](https://docs.zkid.app/introduction/method#verifydidlogin) to help achieve that.

### VC Request Method

#### requestCredentialDigest(params)

```typescript
  public requestCredentialDigest(
    challenge: string,
    ctypehash?: HexString,
    attester?: DidUrl
  ): Promise<VerifiablePresentation> {
    return this.request('did_requestCredentialDigest', { challenge, ctypehash, attester });
  }
```

**Description**

This API is used to obtain a **Digest Disclosure** of a credential, which won't reveal any details of other information. The return result contains some digest information(roothash, `attested` status, `revoked` status) and several helper information (including `ctypeHash`, `owner`, `attester`, `signature`)

If this API returns Error Code `-32001`, it means that the User rejects this request.

If this API returns Error Code `-32801`, it means that the Credential doesn't exist.

If this API returns Error Code `-32010`, it means that the User hasn't give any authorization to this website, the request is not legal.

**Params:**

* `challenge` (required): a random string
* `ctypehash` (optional),the ctypehash of credential, if passed, the wallet will only return the credential with the same `ctypehash`
* `attester` (optional): attester's DID Url

```json
params_example: [{
    "challenge": "..."
    "ctypehash": "0x....",
    "attester": "...",
}]
```

**Return:**

* VerifiablePresentation

**Usage Of Return**

This [`verifyCredentialDigest`](https://docs.zkid.app/introduction/method#verifycredentialdigest) method provided in our SDK can be used to check whether the Digest Disclosure is valid, whether the User is the Credential's Owner.

***

#### requestCredentialContent(params)

```typescript
  public requestCredentialContent(
    challenge: string,
    contentKeys?: string[],
    ctypehash?: HexString,
    attester?: DidUrl
  ): Promise<VerifiablePresentation> {
    return this.request('did_requestCredentialContent', {
      challenge,
      contentKeys,
      ctypehash,
      attester
    });
  }
```

**Description**

This API is used to obtain a **further disclosure** of a credential, developers could use this API to achieve [***Selective Disclosure***](https://docs.zkid.app/readme/usage_of_vc#selective-disclosure) or [***All Credential Content Disclosure***](https://docs.zkid.app/readme/usage_of_vc#all-credential-content-disclosure) via passing different params.

If this API returns Error Code `-32001`, it means that the User rejects this request.

If this API returns Error Code `-32801`, it means that the Credential doesn't exist.

If this API returns Error Code `-32802`, it means that the Credential Metadata doesn't match.

**Params:**

* `challenge` (required): a random string
* `contentKeys` (optional): the content keys need to be disclosed
* `ctypehash` (optional),the ctypehash of credential, if passed, the wallet will only return the credential with the same `ctypehash`
* `attester` (optional): attester's DID Url

```json
params_example: [{
    "challenge": "..."
    "contentKeys": ["...", "...", "..."],
    "ctypehash": "0x....",
    "attester": "...",
}]
```

> Developers will get the ***Selective Disclosure*** result if they pass specific `contentKeys` into this API; Otherwise, if the field `contentKeys` is empty, they will obtain a ***All Credential Content Disclosure***.

**Return:**

* VerifiablePresentation

**Usage Of Return**

This [`verifyCredentialContent`](#VerifyCredentialContent) method provided in our SDK can be used to check whether the Selective Disclosure or All Credential Content Disclosure is valid, whether the User is the Credential's Owner.

***

### DID-Key Method

#### sign(param)

```typescript
public sign(
    data: HexString | Uint8Array | string | number,
    keyId?: DidUrl
  ): Promise<RequestRpcs<'did_sign'>['did_sign'][1]> {
    const payload: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('did_sign', { payload, keyId });
  }
```

**Description**

This API is for users to make a signature on some data via the user's DID `AuthenticationKey`. Once the user has successfully signed, the API returns the result of the user's signature, and developers can verify the validity of the signature through the *Verify Method* in our SDK.

If this API returns Error Code `-32001`, it means that the User rejects this request.

**Param:**

* `data` (required): data to be signed
* `key_Id`(optional): the key used to sign, if not specified, use `authenticationkey` by defalut.

```json
// data is the one to be signed
param: [{
    "data": "0x....."
}]
```

**Return:**

* `HexString` - the user's signature on that data

***

#### encrypt(params)

```typescript
  public encrypt(
    data: HexString | Uint8Array | string | number,
    receiver: DidUrl
  ): Promise<RequestRpcs<'did_encrypt'>['did_encrypt'][1]> {
    const message: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('did_encrypt', { message, receiver });
  }
```

**Description**

This API uses user's and peer's `AgreementKey` to encrypt data, can be used for build secret communication channel. Using this API, both parties of message transmission do not need to worry about message eavesdropping or leakage, encrypted messages can only be read through [Decryption Method](#decrypt-params).

If this API returns Error Code `-32001`, it means that the User rejects this request.

**Params:**

* `data` (required) : the data to be encrypted
* `receiver`:(required): the DID Url of the receiver, used to encrypt

**Return:**

* `HexString` - the encryption result

***

#### decrypt(params)

```typescript
  public decrypt(
    data: HexString | Uint8Array | string | number,
    sender: DidUrl
  ): Promise<HexString> {
    const message: HexString = isHex(data)
      ? data
      : isU8a(data)
      ? u8aToHex(data)
      : isString(data)
      ? stringToHex(data)
      : numberToHex(data);

    return this.request('did_decrypt', { message, sender });
  }
```

**Description**

This API uses user's and peer's `AgreementKey` to decrypt data, can be used for decrypt message transferred by secret communication channel.

If this API returns Error Code `-32001`, it means that the User rejects this request.

**Params**

* `data` (required) : the data to be decrypted
* `sender`:(required): the DID Url of the sender, used to decrypt

**Return:**

* `HexString` - the decryption result

### ZKP Method

#### generateZkp(params)

```typescript
  public generateZkp(
    params: RequestRpcs<'proof_generate'>['proof_generate'][0]
  ): Promise<RequestRpcs<'proof_generate'>['proof_generate'][1]> {
    return this.request('proof_generate', params);
  }
```

**Description**

This API is used to generate zero-knowledge proof with specific `ZKP Program` and `VC`.&#x20;

The `ZKP Program` used should be passed as a parameter. Besides, the `VC` used to run such ZKP Program should also be specified via its `ctypehash` and `attester`.

**Params**

* *ZkpGenRequest*
  * `ctype` (optional) : the specified `ctypehash` of the VC
  * `attester`:(optional): the specified attester's DID Url
  * `program` :(required): String of the ZKP Program

**Return:**

* *ZkpGenResponse*
  * `outputs` - the execution result of the ZKP Program
  * `starkproof` - the zero-knowledge proof of running such ZKP Program
  * `programHash` - the ZKP Program's hash
  * `ctype` - the specified `ctypehash` of the VC
  * `attester` - the specified attester's DID Url