# MTLS API GUIDE

API Base Url: `https://burgan-gw.com/api/mtls`

## Overview

This document serves as a comprehensive guide to API mockups created for MTLS. It outlines endpoints, request/response formats, authentication mechanisms, and use cases to help developers effectively integrate with the API.

## Table of Contents
1. [Introduction](#Introduction)
2. [Endpoints](#Endpoints)
1. [Enrollment](#Enrollment)
2. [Transaction](#Transaction)
3. [Revoke](#Revoke)
3. [Error Handling](#Error-Handling)
4. [Best Practicies](#Best-Practicies)
5. [Changelog](#Changelog)
6. [Links](#Links)

---
## Introduction
Welcome to the API Guide. This API allows you to manage items efficiently. It is designed to be RESTful, adhering to best practices for API design.

## Endpoints
### Enrollment

#### POST /api/certificate/create ####
It creates a new certificate and returns the private key and certificate information.

**Request**
**Method:** POST
**URL:** `/api/certificate/create`

**Body:**

{
  "identity": {
    "deviceId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "tokenId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "requestId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "userTCKN": "123456"
  },
  "instanceId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01"
}

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\n... (certificate data) ...\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n... (private key data) ...\n-----END PRIVATE KEY-----",
    "expirationDate": "2025-03-05T00:00:00Z"
  }
}

---
#### POST /api/certificate/renew ####
It terminates your existing active certificate and generates a new certificate based on your identity information.

**Request**
**Method:** POST
**URL:** `/api/certificate/renew`

**Body:**

{
  "identity": {
    "deviceId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "tokenId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "requestId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "userTCKN": "123456"
  },
  "reason": "string"
}

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----\n... (certificate data) ...\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n... (private key data) ...\n-----END PRIVATE KEY-----",
    "expirationDate": "2025-03-05T00:00:00Z"
  }
}

---
#### GET /api/certificate/status/serial/{CertificateSerialNumber} ####
Returns certificate information based on certificate serial number.

**Request**
**Method:** GET
**URL:** `/api/certificate/status/serial/{CertificateSerialNumber}`

**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| CertificateSerialNumber | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "valid": "true",
    "expirationDate": "2025-03-05T00:00:00Z"
  }
}

---
#### GET /api/certificate/status/serial/{CertificateSerialNumber}/user/{UserTCKN} ####
Returns certificate information based on certificate serial number and user tckn.

**Request**
**Method:** GET
**URL:** `/api/certificate/status/serial/{CertificateSerialNumber}/user/{UserTCKN}
`

**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| CertificateSerialNumber | string | **required** |
UserTCKN | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "valid": "true",
    "expirationDate": "2025-03-05T00:00:00Z"
  }
}

---
#### GET /api/certificate/status/serial/{CertificateSerialNumber}/user/{UserTCKN}/token/{TokenId} ####
Returns certificate information based on certificate serial number, user tckn and token.

**Request**
**Method:** GET
**URL:** `/api/certificate/status/serial/{CertificateSerialNumber}/user/{UserTCKN}/token/{TokenId}
`

**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| CertificateSerialNumber | string | **required** |
UserTCKN | string | **required** |
TokenId | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "valid": "true",
    "expirationDate": "2025-03-05T00:00:00Z"
  }
}

---
#### GET /api/certificate/status/user/{UserTCKN}/token/{TokenId} ####
Returns certificate information based on user tckn and token.

**Request**
**Method:** GET
**URL:** `/api/certificate/status/user/{UserTCKN}/token/{TokenId}
`

**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| UserTCKN | string | **required** |
TokenId | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "valid": "true",
    "expirationDate": "2025-03-05T00:00:00Z"
  }
}

---
#### GET /api/certificate/status/user/{UserTCKN}/device/{DeviceId} ####
Returns certificate information based on user tckn and device id.

**Request**
**Method:** GET
**URL:** `/api/certificate/status/user/{UserTCKN}/device/{DeviceId}
`

**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| UserTCKN | string | **required** |
DeviceId | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "valid": "true",
    "expirationDate": "2025-03-05T00:00:00Z"
  }
}

---
#### GET /api/certificate/status/user/device/{DeviceId} ####
Returns certificate information based on device id.

**Request**
**Method:** GET
**URL:** `/api/certificate/status/user/device/{DeviceId}
`

**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| DeviceId | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "valid": "true",
    "expirationDate": "2025-03-05T00:00:00Z",
    "identity": {
        "deviceId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
        "tokenId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
        "requestId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
        "userTCKN": "123456"
     }
  }
}

---
### Transaction

#### POST api/transaction/create ####
Creates a transaction to sign your data.

**Request**
**Method:** POST
**URL:** `api/transaction/create`

**Body:**

{
  "identity": {
    "deviceId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "tokenId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "requestId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "userTCKN": "123456"
  },
  "intanceId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
  "data": {
      //Data to be signed. Format: JSON
  }
}

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "transactionId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "encryptData": "string",
    "rawData": {
        "nonce": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
        //Data to be signed. Format: JSON
    }
  }
}

---
#### POST api/transaction/{TransactionId}/verify ####
It ensures that the data you sign is verified.

**Request**
**Method:** POST
**URL:** `api/transaction/{TransactionId}/verify`
**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| TransactionId | string | **required** |

**Body:**

{
  "identity": {
    "deviceId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "tokenId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "requestId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
    "userTCKN": "123456"
  },
  "intanceId": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
  "data": {
      "rawData": { //With nonce
          "nonce": "9A4D301-53F5-11CB-8CA0-9CA39A9E1F01",
          //Data to be signed. Format: JSON
      }
      "signData": "string"
  }
}

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "verified": "true"
  }
}

---
### Revoke

#### GET /api/certificate/revoke/token/{TokenId} ####
It revokes the active certificate with the token id.

**Request**
**Method:** GET
**URL:** `/api/certificate/revoke/token/{TokenId}`
**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| TokenId | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "revoked": "true",
    "revocationDate": "2024-03-05T12:00:00Z"
  }
}

---
#### GET /api/certificate/revoke/device/{DeviceId} ####
It revokes the active certificate with the device id.

**Request**
**Method:** GET
**URL:** `/api/certificate/revoke/device/{DeviceId}`
**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| DeviceId | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "revoked": "true",
    "revocationDate": "2024-03-05T12:00:00Z"
  }
}

---
#### GET /api/certificate/revoke/user/{UserTCKN} ####
It revokes the active certificate with the User TCKN.

**Request**
**Method:** GET
**URL:** `/api/certificate/revoke/user/{UserTCKN}`
**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| UserTCKN | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "revoked": "true",
    "revocationDate": "2024-03-05T12:00:00Z"
  }
}

---
#### GET /api/certificate/revoke/id/{CertificateId} ####
It revokes the active certificate with the certificate Id.

**Request**
**Method:** GET
**URL:** `/api/certificate/revoke/id/{CertificateId}`
**Path Params:**

| Params | Type | Description |
| -------- | -------- | -------- |
| CertificateId | string | **required** |

**Response**
**Status Code:** 200 OK

{
  "result": {
    "status": "string",
    "message": "string",
    "messageDetail": "string"
  },
  "data": {
    "revoked": "true",
    "revocationDate": "2024-03-05T12:00:00Z"
  }
}

## Error Handling
The API uses standard HTTP status codes to indicate the success or failure of a request.
* **200 OK:** The request was successful.
* **400 Bad Request:** The request was invalid or cannot be otherwise served.
* **404 Not Found:** The requested resource or entity could not be found.
* **418 Business Error:** Errors that occur when running business logics.
* **422 Not Verified:** Signed data could not be verified.
* **500 Internal Server Error:** An error occurred on the server.

### Example Error Response
**Body:**

{
    "error": {
        "code": 404,
        "message": "",
        "details": "",
        "severity": ""
    }
}

## Best Practicies
DRAFT

## Changelog
**v1.0.0 - 05/2024**
* Initial release with endpoints for managing items.

## Links
* [Client Certificate Creation for Signing and mTLS](https://hackmd.io/X6LqhqvlScmc-dWZZ8BhaQ)
* [Secure Transaction Signing with Mobile App and Secure Element](https://hackmd.io/nTIZw0UeStuoO-M-lVXfXQ)
* [Secure Login with mTLS, PIN, and Signed Challenge](https://hackmd.io/vopJmDFqTXOrwn4f02e08g)