Skip to main content

en-api-key

title: API Key draft: true sidebar_position: 6​

Overview​

The API Key functionality allows the management of access keys for authentication and authorization in the API. Each API Key can have specific permissions associated with it, controlling access to different resources and operations.

⚠️ Authentication Required: All endpoints in this API require authentication via token in the Authorization header. To create API Keys, the user must have user admin permission.

Available Endpoints​

1. List API Keys​

GET /api-key

Returns a list of all registered API Keys.

Response​

[
  {
    "permissions": [
      {
        "id": 34,
        "name": ""
      }
    ],
    "id": "cf596aa0-d340-4bcf-8eb4-c9525d27f723",
    "key_mask": "ddf_Vtfoc***************************************",
    "created_at": "2025-06-06T19:05:30.999Z"
  }
]

2. Create New API Key​

POST /api-key

Creates a new API Key with the specified permissions.

Request Body​

{
  "permissions": [1, 2, 3]
}

Parameters​

  • permissions (array of numbers, required): Array containing the IDs of permissions to be associated with the API Key

Note: To get the list of available permissions, use the GET /permissions endpoint

Success Response (201)​

{
  "permissions": [
    {
      "id": 34,
      "name": ""
    }
  ],
  "id": "484d8b37-dfe8-4335-b3b1-9ce87a809edf",
  "key": "ddf_FSdgV8Ii2py/7sexFE3H9yyNvxuBQ2jn7mksKomfXy8=",
  "key_mask": "ddf_FSdgV***************************************",
  "created_at": "2025-06-20T21:05:48.814Z",
  "created_by": "9488a4e8-a0e1-7046-f441-1c5fa95a9966"
}

Error Response (500)​

{
  "statusCode": 500,
  "message": "An unknown error occurred. If the error persists, please contact support",
  "error": "Oops... Unable to perform your action",
  "code": "UNKNOWN",
  "details": "Invalid permission IDs: 0"
}

3. Delete API Key​

DELETE /api-key/:id

Removes a specific API Key from the system.

URL Parameters​

  • id (string, required): ID of the API Key to be deleted

Success Response (204)​

No content in the response body.

Error Response (404)​

{
  "error": "API Key not found",
  "message": "API Key with ID 123 was not found"
}

Usage Examples​

Creating an API Key with Specific Permissions​

  1. First, check available permissions:

    curl -X GET https://maestro.dadosfera.ai/permissions \
      -H "Authorization: your_token_here"

  2. Create the API Key with desired permissions:

    curl -X POST https://maestro.dadosfera.ai/api-key \
      -H "Content-Type: application/json" \
      -H "Authorization: your_admin_token_here" \
      -d '{"permissions": [1, 2]}'

  3. Verify if the API Key was created:

    curl -X GET https://maestro.dadosfera.ai/api-key \
      -H "Authorization: your_token_here"

Removing an API Key​

curl -X DELETE https://maestro.dadosfera.ai/api-key/2 \
  -H "Authorization: your_token_here"

Important Notes​

  • Authentication: All operations require an authorization token. Only users with admin permission can create API Keys
  • API Keys are automatically generated by the system in the format ddf_ followed by an encoded string
  • The POST response contains both the complete key (key) and a masked version (key_mask) for security
  • In GET requests, only the masked version is returned for security reasons
  • An API Key cannot be created without at least one valid permission
  • When deleting an API Key, the key will be invalidated immediately
  • Permission IDs must exist in the system, otherwise API Key creation will fail
  • It is recommended to follow the principle of least privilege, granting only the strictly necessary permissions