CertFusion

Endpoint: GET /api/lists

Description:
Retrieve a list of all certificate lists associated with the authenticated user.

Method: GET

Authentication:
Requires user authentication via token (e.g., Bearer Token).

Request Parameters:

  • page (optional):
    The page number for pagination. Default is 1.

  • per_page (optional):
    Number of results per page. Default is 15. Max is configurable depending on your application.

Request Headers:

  • Authorization: Bearer <token>
    A valid API token must be included in the request header to authenticate the user.

Response:

  • Status Code: 200 OK

Response Body:

{
  "data": [
    {
      "id": 1,
      "name": "Certificate List 1",
      "created_at": "2023-10-01T12:00:00.000000Z",
      "updated_at": "2023-10-02T12:00:00.000000Z"
    },
    {
      "id": 2,
      "name": "Certificate List 2",
      "created_at": "2023-10-02T12:30:00.000000Z",
      "updated_at": "2023-10-03T14:00:00.000000Z"
    }
  ],
  "links": {
    "first": "http://example.com/api/lists?page=1",
    "last": "http://example.com/api/lists?page=5",
    "prev": null,
    "next": "http://example.com/api/lists?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 75
  }
}

Response Fields:

  • data: A collection of certificate lists.

    • id: The unique identifier of the list.
    • name: The name of the certificate list.
    • created_at: The date and time when the certificate list was created.
    • updated_at: The date and time when the certificate list was last updated.

  • links: Pagination links.

    • first: URL to the first page of results.
    • last: URL to the last page of results.
    • prev: URL to the previous page of results, if applicable.
    • next: URL to the next page of results, if applicable.

  • meta: Pagination metadata.

    • current_page: The current page number.
    • from: The starting index of the current page of results.
    • last_page: The last page number.
    • per_page: The number of items per page.
    • to: The ending index of the current page of results.
    • total: The total number of available certificate lists.

Errors:

  • 401 Unauthorized: If the user is not authenticated.
  • 500 Internal Server Error: If there is an issue with retrieving the certificate lists.

Endpoint: GET /api/recipients

Description:
Retrieve a list of all recipients associated with certificate lists belonging to the authenticated user.

Method: GET

Authentication:
Requires user authentication via token (e.g., Bearer Token).

Request Parameters:

  • page (optional):
    The page number for pagination. Default is 1.

  • per_page (optional):
    Number of results per page. Default is 15. Max is configurable depending on your application.

Request Headers:

  • Authorization: Bearer <token>
    A valid API token must be included in the request header to authenticate the user.

Response:

  • Status Code: 200 OK

Response Body:

{
  "data": [
    {
      "id": 1,
      "list_id": 1,
      "email": "recipient@example.com",
      "name": "John Doe",
      "status": "issued",
      "uuid": "abcd-1234-efgh-5678",
      "issued_date": "2023-10-01T12:00:00+00:00",
      "created_at": "2023-10-01T12:00:00+00:00",
      "updated_at": "2023-10-02T12:00:00+00:00"
    },
    {
      "id": 2,
      "list_id": 2,
      "email": "another@example.com",
      "name": "Jane Smith",
      "status": "draft",
      "uuid": "ijkl-5678-mnop-1234",
      "issued_date": "2023-09-28T10:00:00+00:00",
      "created_at": "2023-09-28T10:00:00+00:00",
      "updated_at": "2023-09-29T10:00:00+00:00"
    }
  ],
  "links": {
    "first": "http://example.com/api/recipients?page=1",
    "last": "http://example.com/api/recipients?page=5",
    "prev": null,
    "next": "http://example.com/api/recipients?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 75
  }
}

Response Fields:

  • data: A collection of recipient records.

    • id: The unique identifier of the recipient.
    • list_id: The ID of the certificate list the recipient is associated with.
    • email: The email address of the recipient.
    • name: The name of the recipient.
    • status: The current status of the recipient (e.g., draft, issued).
    • uuid: A unique identifier for the recipient (e.g., a GUID).
    • issued_date: The date when the certificate was issued to the recipient. If not set, null will be returned.
    • created_at: The timestamp when the recipient was created.
    • updated_at: The timestamp when the recipient was last updated.

  • links: Pagination links.

    • first: URL to the first page of results.
    • last: URL to the last page of results.
    • prev: URL to the previous page of results, if applicable.
    • next: URL to the next page of results, if applicable.

  • meta: Pagination metadata.

    • current_page: The current page number.
    • from: The starting index of the current page of results.
    • last_page: The last page number.
    • per_page: The number of items per page.
    • to: The ending index of the current page of results.
    • total: The total number of available recipients.

Errors:

  • 401 Unauthorized: If the user is not authenticated.
  • 500 Internal Server Error: If there is an issue with retrieving the recipients.

Endpoint: POST /api/recipients

Description:
Add a new recipient to a certificate list associated with the authenticated user.

Method: POST

Authentication:
Requires user authentication via token (e.g., Bearer Token).

Request Parameters (Body):

{
  "list_id": 1,
  "email": "recipient@example.com",
  "name": "John Doe"
}

  • list_id (required, integer):
    The ID of the certificate list the recipient will be added to. This list must exist and belong to the authenticated user.

  • email (required, string):
    The email address of the recipient. It must be a valid email format.

  • name (required, string):
    The full name of the recipient. Maximum length is 255 characters.

Request Headers:

  • Authorization: Bearer <token>
    A valid API token must be included in the request header to authenticate the user.

Response:

  • Status Code: 201 Created (on success)
    When the recipient is successfully created, the response will include the recipient’s details.

Response Body (Success):

{
  "id": 1,
  "list_id": 1,
  "email": "recipient@example.com",
  "name": "John Doe",
  "status": "active",  
  "uuid": "abcd-1234-efgh-5678",
  "issued_date": null,
  "created_at": "2023-10-01T12:00:00+00:00",
  "updated_at": "2023-10-01T12:00:00+00:00"
}
  • id: The unique identifier of the recipient.
  • list_id: The ID of the certificate list the recipient is associated with.
  • email: The email address of the recipient.
  • name: The name of the recipient.
  • status: The status of the recipient (e.g., active, inactive).
  • uuid: A unique identifier for the recipient (UUID).
  • issued_date: The date when the certificate was issued to the recipient. If not issued yet, null.
  • created_at: The timestamp when the recipient was created.
  • updated_at: The timestamp when the recipient was last updated.

Response (Errors):

  1. 400 Bad Request:
    If required parameters are missing or invalid, such as an invalid email format.

    Response Example:

    {
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "email": ["The email must be a valid email address."]
  }
}

  2. 404 Not Found:
    If the specified list_id does not exist, or if the list does not belong to the authenticated user.

    Response Example:

    {
  "status": false,
  "message": "The list you are trying to access does not exist."
}

  3. 403 Forbidden:
    If the authenticated user does not have permission to access the specified list.

    Response Example:

    {
  "status": false,
  "message": "You are not authorized to perform this action."
}

  4. 422 Unprocessable Entity:
    If the input validation fails (e.g., missing required fields).

    Response Example:

    {
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "name": ["The name field is required."]
  }
}

  5. 500 Internal Server Error:
    If there is an unexpected server error during recipient creation.

    Response Example:

    {
  "status": false,
  "message": "An error occurred while creating the recipient.",
  "error": "Error details here"
}

Endpoint: DELETE /api/recipients/{id}

Description:
Delete a recipient from a certificate list associated with the authenticated user.

Method: DELETE

Authentication:
Requires user authentication via token (e.g., Bearer Token).

URL Parameters:

  • id (required, integer):
    The unique ID of the recipient that you want to delete.

Request Headers:

  • Authorization: Bearer <token>
    A valid API token must be included in the request header to authenticate the user.

Response:

  • Status Code: 200 OK (on success)
    When the recipient is successfully deleted, the response will include a success message.

Response Body (Success):

{
  "status": true,
  "message": "Recipient deleted successfully."
}

Response Fields:

  • status: Indicates whether the operation was successful (true or false).
  • message: A message describing the result of the operation.

Response (Errors):

  1. 404 Not Found:
    If the recipient does not exist or is not associated with the authenticated user.

    Response Example:

    {
  "status": false,
  "message": "Recipient not found or not associated with your account."
}

  2. 500 Internal Server Error:
    If an unexpected error occurs during the deletion process.

    Response Example:

    {
  "status": false,
  "message": "An error occurred while deleting the recipient.",
  "error": "Error details here"
}

Endpoint: POST /api/recipients/{id}/issue

Description:
Issue a certificate to a specific recipient in the authenticated user's certificate list.

Method: POST

Authentication:
Requires user authentication via token (e.g., Bearer Token).

URL Parameters:

  • id (required, integer):
    The unique ID of the recipient for whom the certificate is to be issued.

Request Headers:

  • Authorization: Bearer <token>
    A valid API token must be included in the request header to authenticate the user.

Response:

  • Status Code: 200 OK (on success)
    When the certificate is successfully issued, the response will include the recipient's details.

Response Body (Success):

{
  "status": true,
  "recipient": {
    "id": 1,
    "list_id": 1,
    "email": "recipient@example.com",
    "name": "John Doe",
    "status": "issued",  
    "uuid": "abcd-1234-efgh-5678",
    "issued_date": "2023-10-01T12:00:00+00:00",
    "created_at": "2023-10-01T12:00:00+00:00",
    "updated_at": "2023-10-01T12:00:00+00:00"
  }
}
  • status: Indicates whether the operation was successful (true).
  • recipient: Contains the updated recipient details including the issued_date and other recipient-related information.

Response (Errors):

  1. 404 Not Found:
    If the recipient does not exist or is not associated with the authenticated user.

    Response Example:

    {
  "status": false,
  "message": "Recipient not found or you do not have access to this recipient."
}

  2. 500 Internal Server Error:
    If an unexpected error occurs while issuing the certificate.

    Response Example:

    {
  "status": false,
  "message": "An error occurred while issuing the certificate.",
  "error": "Error details here"
}

Endpoint: POST /api/recipients/issue

Description:
Issue certificates to a group of recipients belonging to the authenticated user's certificate lists.

Method: POST

Authentication:
Requires user authentication via token (e.g., Bearer Token).

Request Body:

{
  "recipient_ids": [1, 2, 3]
}
  • recipient_ids (required, array of integers):
    An array of recipient IDs for whom the certificates will be issued.

Request Headers:

  • Authorization: Bearer <token>
    A valid API token must be included in the request header to authenticate the user.

Response:

  • Status Code: 200 OK (on success)
    When the certificates are successfully issued to the group of recipients, the response will include the list of updated recipients.

Response Body (Success):

{
  "status": true,
  "recipients": [
    {
      "id": 1,
      "list_id": 1,
      "email": "recipient1@example.com",
      "name": "John Doe",
      "status": "issued",
      "uuid": "abcd-1234-efgh-5678",
      "issued_date": "2023-10-01T12:00:00+00:00",
      "created_at": "2023-10-01T12:00:00+00:00",
      "updated_at": "2023-10-01T12:00:00+00:00"
    },
    {
      "id": 2,
      "list_id": 1,
      "email": "recipient2@example.com",
      "name": "Jane Doe",
      "status": "issued",
      "uuid": "ijkl-2345-mnop-6789",
      "issued_date": "2023-10-01T12:00:00+00:00",
      "created_at": "2023-10-01T12:00:00+00:00",
      "updated_at": "2023-10-01T12:00:00+00:00"
    }
  ]
}
  • status: Indicates whether the operation was successful (true).
  • recipients: A collection of recipient objects, each containing the updated details such as issued_date and other recipient-related information.

Response (Errors):

  1. 422 Unprocessable Entity (Validation Error):
    If the recipient_ids array is invalid or the IDs do not exist in the database.

    Response Example:

    {
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "recipient_ids": [
      "The selected recipient_ids is invalid."
    ]
  }
}

  2. 404 Not Found:
    If no valid recipients are found or the authenticated user does not have access to them.

    Response Example:

    {
  "status": false,
  "message": "No valid recipients found or you do not have access to them."
}

  3. 500 Internal Server Error:
    If an unexpected error occurs while issuing the certificates.

    Response Example:

    {
  "status": false,
  "message": "An error occurred while issuing certificates.",
  "error": "Error details here"
}