Security management
As an Atlassian Data Center administrator, you can manage the lifecycle of AES keys generated by Jira Data Center through a set of REST APIs. These APIs allow you to manage keys either manually or programmatically.
These APIs don't apply to the AES keys that encrypt user directory passwords.
AES key management API
This API provides endpoints for rotating AES keys, retrieving inactive keys, and deleting inactive keys. Below you will find detailed descriptions of each endpoint, including the URL, accepted HTTP methods, possible response codes, and their meanings.
Endpoints
1. Rotate AES Key
This endpoint is used to rotate the AES encryption key. Existing secrets will be re-encrypted with the new key.
Method:
POSTURL:
https://<HOSTNAME>:<PORT>/rest/secrets/1.0/keys/rotateQuery parameters: None
Request body: None
Response Codes
200 OK: Returned if the AES key was rotated successfully.
401 Unauthorized: Returned if the user is not authorized to perform the operation.
406 Not Acceptable: Returned if the rotation cannot occur due to invalid conditions.
500 Internal Server Error: Returned if an unexpected error occurs when performing the operation.
Response body
{
"message": "<detailed_message>",
"status": "<rotation_status>"
}2. Get Inactive AES Keys
Once key rotation is completed, the old AES key becomes inactive. This endpoint retrieves a list of inactive AES key(s).
Method:
GETURL:
https://<HOSTNAME>:<PORT>/rest/secrets/1.0/keys/inactiveQuery parameters: None
Request body: None
Response Codes
200 OK: Returned if the inactive AES key(s) were retrieved successfully.
401 Unauthorized: Returned if the user is not authorized to perform the operation.
500 Internal Server Error: Returned if an unexpected error occurs when performing the operation.
Response body
{
"inactiveKeys": [
"<inactive_key_name>"
]
}3. Delete Inactive AES Keys
Once key rotation is completed, the old AES key becomes inactive. This endpoint deletes all inactive AES key(s).
Method:
DELETEURL:
https://<HOSTNAME>:<PORT>/rest/secrets/1.0/keys/inactiveQuery parameters: None
Request body: None
Response Codes
200 OK: Returned if the inactive AES key(s) were deleted successfully.
401 Unauthorized: Returned if the user is not authorized to perform the operation.
500 Internal Server Error: Returned if an unexpected error occurs when performing the operation.
Response body
{
"deletedKeys": [
"<deleted_key_name>"
]
}Audit logging
Key rotation and deletion events can all be found in the Jira audit logs.
Troubleshooting and tips
Authorization
All endpoints require the user to be authorized. Ensure that you include the appropriate authorization headers with your requests.
Error Handling
In the event of a 500 response (Internal Server Error), check the application logs for more details on what might have gone wrong.
If you receive a 401 response (Unauthorized), verify your credentials and permissions.
Usage Notes
Ensure that you replace <HOSTNAME> and <PORT> with the actual host and port of your DC instance.