Certicheck

API Key Routes ​

This page provides the routes for managing API keys in the application.

GET /api-key ​

Retrieves a list of API keys based on query parameters.

Description: This endpoint retrieves a list of API keys based on the provided query parameters.

Authentication: This route requires authentication with the USER role and the api_key_management and read permission.

Query Parameters:

  • _id (optional): Filter API keys by ID.
  • createdBy (optional): Filter API keys by the ID of the user who created them.
  • key (optional): Filter API keys by the key value.
  • name (optional): Filter API keys by name.
  • orgId (optional): Filter API keys by organization ID.
  • purpose (optional): Filter API keys by purpose.

Response:

  • 200 OK with the api keys returned
json
[
  {
    "_id": "6673c073befd387cfc4fb7a0",
    "createdBy": "66605eaedd7f7aae27752dda",
    "key": "07441211fdac187163c5d3fcd7ca2c68",
    "name": "Test API",
    "orgId": "666141dbfe2a0781e76f6549",
    "purpose": "test purpose",
    "scopes": ["read"],
    "createdAt": "2024-06-20T05:38:59.110Z",
    "updatedAt": "2024-06-20T05:38:59.110Z",
    "__v": 0
  }
]

Errors:

  • 400 Bad Request if the query contains invalid data.
  • 401 Unauthorized if the user is not authenticated or does not have the required permissions.
  • 500 Internal Server Error if there is an issue getting the api in the database.

Usage: To retrieve a list of API keys, send a GET request to /api-key. You can include query parameters to filter the results, such as name, key, orgId, or purpose.

POST /api-key ​

Creates a new API key.

Description: This endpoint creates a new API key for the authenticated user.

Authentication: This route requires authentication with the USER role and the api_key_management and create permission.

Request Body:

json
{
  "name": "test", // (string, required): The name of the API key.
  "purpose": "for testing", // (string, required): The purpose of the API key.
  "scopes": ["write", "read"] // (array, required): The scopes of the API key.
}

Response:

  • 201 Created with the api keys returned
json
{
  "createdBy": "667e52015767249ca5838bfa",
  "key": "RuseFkU26vRhoWWI9BIQ==:wPAEB0EwWf7qxSLR4uv3N78Rsxa6nZs8LbTsHMWpGnE=",
  "name": "test",
  "orgId": "666141dbfe2a0781e76f6549",
  "purpose": "for testing",
  "scopes": ["write", "read"],
  "_id": "667e55d14b2a3d38b8cb1c64",
  "createdAt": "2024-06-28T06:18:57.762Z",
  "updatedAt": "2024-06-28T06:18:57.762Z",
  "__v": 0
}

Errors:

  • 400 Bad Request if the request body is missing required fields or contains invalid data.
  • 401 Unauthorized if the user is not authenticated or does not have the required permissions.
  • 500 Internal Server Error if there is an issue creating the api in the database.

Usage: To create a new API key, send a POST request to /api-key with a JSON request body containing the name ,purpose, and scope of the new API key.

GET /api-key/user/:userId ​

Retrieves a list of API keys for a specific user.

Description: This endpoint retrieves a list of API keys associated with the specified user ID.

Authentication: This route requires authentication with the USER role and the api_key_management and read permission.

Parameters:

  • userId (required): The ID of the user to retrieve API keys for.

Response:

  • 200 OK with the api keys returned
json
[
  {
    "_id": "6673bff1dd4d7bc47f24343c",
    "createdBy": "66605eaedd7f7aae27752dda",
    "key": "b6ef9be0d590beb872ca50cb19a58139",
    "name": "Test API",
    "orgId": "666141dbfe2a0781e76f6542",
    "purpose": "test purpose",
    "scopes": ["read"],
    "createdAt": "2024-06-20T05:36:49.880Z",
    "updatedAt": "2024-06-20T05:36:49.880Z",
    "__v": 0
  }
]

Errors:

  • 400 Bad Request if the query contains invalid data.
  • 401 Unauthorized if the user is not authenticated or does not have the required permissions.
  • 500 Internal Server Error if there is an issue getting api in the database.

Usage: To retrieve a list of API keys for a specific user, send a GET request to /api-key/user/:userId, replacing :userId with the ID of the user you want to retrieve API keys for.

GET /api-key/my ​

Retrieves a list of API keys for the authenticated user.

Description: This endpoint retrieves a list of API keys associated with the authenticated user.

Authentication: This route requires authentication with the USER role and the api_key_management and read permission.

Response:

  • 200 OK with the api keys returned
json
[
  {
    "_id": "6673bff1dd4d7bc47f24343c",
    "createdBy": "66605eaedd7f7aae27752dda",
    "key": "b6ef9be0d590beb872ca50cb19a58139",
    "name": "Test API",
    "orgId": "666141dbfe2a0781e76f6542",
    "purpose": "test purpose",
    "scopes": ["read"],
    "createdAt": "2024-06-20T05:36:49.880Z",
    "updatedAt": "2024-06-20T05:36:49.880Z",
    "__v": 0
  }
]

Errors:

  • 400 Bad Request if any invalid data.
  • 401 Unauthorized if the user is not authenticated or does not have the required permissions.
  • 500 Internal Server Error if there is an issue in the database.

Usage: To retrieve a list of API keys for the authenticated user, send a GET request to /api-key/my.

GET /api-key/my/organization ​

Retrieves a list of API keys for the authenticated user's organization.

Description: This endpoint retrieves a list of API keys associated with the authenticated user's organization.

Authentication: This route requires authentication with the OWNER role and the api_key_management and read permission.

Response:

Response:

  • 200 OK with the api keys returned
json
[
  {
    "_id": "6673bff1dd4d7bc47f24343c",
    "createdBy": "66605eaedd7f7aae27752dda",
    "key": "b6ef9be0d590beb872ca50cb19a58139",
    "name": "Test API",
    "orgId": "666141dbfe2a0781e76f6542",
    "purpose": "test purpose",
    "scopes": ["read"],
    "createdAt": "2024-06-20T05:36:49.880Z",
    "updatedAt": "2024-06-20T05:36:49.880Z",
    "__v": 0
  }
]

Errors:

  • 400 Bad Request if any invalid data.
  • 401 Unauthorized if the user is not authenticated or does not have the required permissions.
  • 500 Internal Server Error if there is an issue in the database.

Usage: To retrieve a list of API keys for the authenticated user's organization, send a GET request to /api-key/my/organization.

GET /api-key/:apiKeyId ​

Retrieves details of a specific API key by ID.

Description: This endpoint retrieves the details of a specific API key based on the provided ID.

Authentication: This route requires authentication with the USER role and the api_key_management and read permission.

Parameters:

  • apiKeyId (required): The ID of the API key to retrieve.

Response:

  • 200 OK with the api keys returned
json
[
  {
    "_id": "6673bff1dd4d7bc47f24343c",
    "createdBy": "66605eaedd7f7aae27752dda",
    "key": "b6ef9be0d590beb872ca50cb19a58139",
    "name": "Test API",
    "orgId": "666141dbfe2a0781e76f6542",
    "purpose": "test purpose",
    "scopes": ["read"],
    "createdAt": "2024-06-20T05:36:49.880Z",
    "updatedAt": "2024-06-20T05:36:49.880Z",
    "__v": 0
  }
]

Errors:

  • 400 Bad Request if any invalid data.
  • 401 Unauthorized if the user is not authenticated or does not have the required permissions.
  • 500 Internal Server Error if there is an issue in the database.

Usage: To retrieve the details of a specific API key, send a GET request to /api-key/:apiKeyId, replacing :apiKeyId with the ID of the API key you want to retrieve.

DELETE /api-key/:apiKeyId ​

Deletes an API key by ID.

Description: This endpoint deletes an existing API key with the provided ID.

Authentication: This route requires authentication with the USER role and the api_key_management and delete permission.

Parameters:

  • apiKeyId (required): The ID of the API key to delete.

Response:

  • 200 OK with success message.
json
{
  "message": "Api key deleted successfully",
  "status": "success"
}

Errors:

  • 400 Bad Request if any invalid data.
  • 401 Unauthorized if the user is not authenticated or does not have the required permissions.
  • 404 Not Found if the API key does not exist.
  • 500 Internal Server Error if there is an issue in the database.

Usage: To delete an existing API key, send a DELETE request to /api-key/:apiKeyId, replacing :apiKeyId with the ID of the API key you want to delete.

API Documentation created with ❤️ by TrackGenesis

Copyright © 2025 TrackGenesis®