Shared Link API and Routes

This page provides detailed information about the Shared Link API and routes.

Shared Link API Description

The Shared Link API provides endpoints for managing shared links. It allows you to create shared links, retrieve a list of shared links, and revoke a shared link.

Shared Link Routes

The following routes are available for managing shared links:

POST /shared-links

Creates a new shared link.

Description: This endpoint creates a new shared link.

Authentication: Requires authentication with the RECIPIENT token.

Request Body:

• certificateIds: (Array of Strings) - An array of certificate IDs.
• expiry: (Date) - The expiry date of the shared link.
• permission: (String) - The permission of the shared link. It can be either 'view' or 'download'.
• sharedWith: (Array of Strings) - [Optional] An array of email addresses.
• password: (String) - [Optional] The password of the shared link.

Request Example

{
  "certificateIds": ["certificateId1", "certificateId2"],
  "sharedWith": ["email1", "email2"], // optional, only required if permission is not `anyone`
  "expiry": "2022-12-31T23:59:59.999Z",
  "permission": "view",
  "password": "password" // optional
}

Response:

• status: (Number) - The HTTP status code of the response.
• data: (Object) - The data of the response.
  • link: (String) - The link of the shared link.

Example Response

{
  "status": 200,
  "data": {
    "link": "https://example.com"
  }
}

Errors:

• 400 Bad Request - If the request body is missing or invalid.
• 401 Unauthorized - If the user is not authenticated.
• 403 Forbidden - If the user is not authorized to create a shared link.
• 500 Internal Server Error - If there is an error in the server while creating the shared link.

GET /shared-links

Retrieves all shared links.

Description: This endpoint retrieves all shared links.

Authentication: Requires authentication with the RECIPIENT token.

Response:

• status: (Number) - The HTTP status code of the response.
• data: (Array of Objects) - The data of the response.
  • certificateIds: (Array of Strings) - The certificate IDs associated with the shared link.
  • createdAt: (Date) - The creation date of the shared link.
  • createdBy: (ObjectId) - The ID of the user who created the shared link.
  • expiry: (Date) - The expiry date of the shared link.
  • hasPassword: (Boolean) - Indicates whether the shared link has a password or not.
  • id: (String) - The ID of the shared link.
  • link: (String) - The link of the shared link.
  • password: (String) - If the shared link has a password, this field contains the password. Otherwise, it is not present in the response.
  • permission: (String) - The permission of the shared link. It can be either 'view' or 'download'.
  • sharedWith: (Array of Strings) - The email addresses of the users who have shared the link. Only present if sharedWith is not anyone.
  • updatedAt: (Date) - The last update date of the shared link.

Example Response

{
  "status": 200,
  "data": [
    {
      "certificateIds": ["certificateId1", "certificateId2"],
      "createdAt": "2022-12-31T23:59:59.999Z",
      "createdBy": "userId",
      "expiry": "2022-12-31T23:59:59.999Z",
      "hasPassword": false,
      "id": "sharedLinkId",
      "link": "https://example.com",
      "permission": "view",
      "updatedAt": "2022-12-31T23:59:59.999Z"
    },
    {
      "certificateIds": ["certificateId3", "certificateId4"],
      "createdAt": "2022-12-31T23:59:59.999Z",
      "createdBy": "userId",
      "expiry": "2022-12-31T23:59:59.999Z",
      "hasPassword": true,
      "id": "sharedLinkId2",
      "link": "https://example.com",
      "password": "password",
      "permission": "download",
      "sharedWith": ["email3", "email4"],
      "updatedAt": "2022-12-31T23:59:59.999Z"
    }
  ]
}

Errors:

• 401 Unauthorized - If the user is not authenticated.
• 500 Internal Server Error - If there is an error in the server while retrieving the shared links.

POST /shared-links/:linkId

Retrieves a shared link by its ID.

Description: This endpoint retrieves a shared link by its ID.

Request Parameters:

• linkId: (String) - The ID of the shared link to retrieve.

Request Body:

• password: (String) - The password of the shared link to retrieve, if it exists.

Response:

• status: (Number) - The HTTP status code of the response.
• data: (Object) - The data of the response.
  • certificateIds: (Array of Strings) - The certificate IDs associated with the shared link.
  • expiry: (Date) - The expiry date of the shared link.
  • permission: (String) - The permission of the shared link. It can be either 'view' or 'download'.

Example Response

{
  "status": 200,
  "data": {
    "certificateIds": ["certificateId1", "certificateId2"],
    "expiry": "2022-12-31T23:59:59.999Z",
    "permission": "view"
  }
}

Errors:

• 401 Unauthorized - If the user is not authenticated.
• 404 Not Found - If the shared link with the given ID is not found.
• 400 Bad Request - If the password is missing or invalid.
• 500 Internal Server Error - If there is an error in the server while retrieving the shared link.

DELETE /shared-links/:linkId

Revokes a shared link.

Description: This endpoint revokes a shared link.

Authentication: Requires authentication with the RECIPIENT token.

Request Parameters:

• linkId: (String) - The ID of the shared link to revoke.

Response:

• status: (Number) - The HTTP status code of the response.
• data: (Object) - The data of the response.
  • success: (Boolean) - Indicates whether the shared link was successfully revoked or not.

Errors:

• 401 Unauthorized - If the user is not authenticated.
• 404 Not Found - If the shared link with the given ID is not found.
• 500 Internal Server Error - If there is an error in the server while revoking the shared link.

GET /shared-links/email

Retrieves all shared links associated with an email.

Description: This endpoint retrieves all shared links associated with an email.

Authentication: Requires authentication with the AGENCY token.

Response:

• status: (Number) - The HTTP status code of the response.

• data: (Array of Objects) - The data of the response.

  • email: (String) - The email address of the user who shared the link.

  • links: (Array of Objects) - The shared links associated with the user.

    • certificateIds: (Array of Strings) - The certificate IDs associated with the shared link.
    • createdAt: (Date) - The creation date of the shared link.
    • expiry: (Date) - The expiry date of the shared link.
    • hasPassword: (Boolean) - Indicates whether the shared link has a password or not.
    • id: (String) - The ID of the shared link.
    • link: (String) - The link of the shared link.
    • permission: (String) - The permission of the shared link. It can be either 'view' or 'download'.
    • updatedAt: (Date) - The last update date of the shared link.

Example Response

[
  {
    "email": "recipient@email.com",
    "links": [
      {
        "certificateIds": ["certificateId1", "certificateId2"],
        "expiry": "2024-08-24T00:00:00.000Z",
        "permission": "download",
        "createdAt": "2024-08-21T11:34:01.048Z",
        "updatedAt": "2024-08-21T11:34:01.048Z",
        "link": "https://certicheck.web3sandpit.com/shared/66c5d0a9d1f7fdf46f9534ae?hasPassword=false",
        "hasPassword": false,
        "id": "66c5d0a9d1f7fdf46f9534ae"
      },
      {
        "certificateIds": ["certificateId3", "certificateId4"],
        "expiry": "2024-08-23T00:00:00.000Z",
        "permission": "download",
        "createdAt": "2024-08-21T11:27:47.612Z",
        "updatedAt": "2024-08-21T11:27:47.612Z",
        "link": "https://certicheck.web3sandpit.com/shared/66c5cf33d192dfe9aa1d4bf8?hasPassword=false",
        "hasPassword": false,
        "id": "66c5cf33d192dfe9aa1d4bf8"
      }
    ]
  }
]