-
Notifications
You must be signed in to change notification settings - Fork 75
v1.1.0 Addendum for The Developer Guide to the CVE Services
This is an temporary addendum page for the developer guide until the v1.1.0 release makes it to production where this addendum will then become part of the living page.
First and foremost, the endpoint to reserve IDs will not change! That is the POST /cve-id endpoint and does not pertain to this notice. Your integration with reservation will continue to function with the new release.
But it was discovered that the development team needed to adjust the endpoint for getting a list of CVE IDs to utilize pagination as early as possible in order to support more traffic in the future. It was best to add this as soon as possible and is a minor but breaking change to the endpoint. If you have already managed to integrate with the list CVE IDs endpoint and you expect your queries to result in a list of CVE IDs that exceeds 500, the service will now only give 500 of the IDs and include a field to use to request the rest (or the next set of 500) IDs that fit that query. It's important to note that if your tooling never constructs a query that would result in over 500 IDs returned, you will not experience an issue. Still, it would be best to prepare said tooling to simply catch the pagination field and utilize it for a more robust integration. We apologize for any inconvenience this may cause, and we have made sure to always include pagination for any new list endpoints from the start to avoid encountering this issue in the future.
With v1.1.0, many endpoints were developed to enable clients to perform administrative duties. Now, users can modify some of their own data and reset their own API key, as well as view other users in their organization. An additional role was also implemented, Org Admin, which can perform the same functions on other users within the same organization along with the ability to deactivate users. For now, with v1.1.0, the Secretariat is the only account able to "upgrade" a user account to an Org Admin account. The following are example requests for the new endpoints.
Secretariat:
A user associated with an Org possessing the Secretariat role can reset any account's secret.
Org Admin:
A user with the Org Admin role can reset secrets for any user in their Org.
General User:
A general user can only reset their own secret.
Example request:
curl --location -g --request PUT 'https://cveawg.mitre.org/api/org/education/user/[email protected]/reset_secret' \
--header 'CVE-API-USER: [email protected]' \
--header 'CVE-API-ORG: education' \
--header 'CVE-API-KEY: <key>'Example response:
{
"API-secret": "<secret>"
}Secretariat:
A user associated with an Org possessing the Secretariat role can update any account's data.
Org Admin:
A user with the Org Admin role can update any account's data for any user in their Org.
General User:
A general user can only update their own data.
This example only shows a request that changes an account's username. For more parameters, refer to the Open API spec.
Example request:
curl --location --request PUT 'https://cveawg.mitre.org/api/org/education/user/[email protected]?new_username=aclark' \
--header 'CVE-API-USER: [email protected]' \
--header 'CVE-API-ORG: education' \
--header 'CVE-API-KEY: <key>'Example response:
{
user: {
username: String, //(should be new username)
org_UUID: String,
UUID: String,
active: Boolean,
name: { // first, last, middle, surname, suffix },
authority: {
active_roles: [ADMIN || EMPTY]
}
}
}Secretariat:
A user associated with an Org possessing the Secretariat role can list any Org's users.
Org Admin:
A user with the Org Admin role can list users for their Org.
General User:
A general user can list users for their Org.
Example request:
curl --location --request GET 'https://cveawg.mitre.org/api/org/education/users' \
--header 'CVE-API-USER: [email protected]' \
--header 'CVE-API-ORG: education' \
--header 'CVE-API-KEY: <key>'Example response:
{
totalCount: number,
users: [
{
username: String,
org_UUID: String,
UUID: String,
active: Boolean,
name: { // first, last, middle, surname, suffix },
authority: {
active_roles: [ADMIN || EMPTY]
}
}
]
}Secretariat:
A user associated with an Org possessing the Secretariat role can look up any Org's users.
Org Admin:
A user with the Org Admin role can look up any user for their Org.
General User:
A general user can look up any user for their Org.
Example request:
curl --location --request GET 'https://cveawg.mitre.org/api/org/education/user/[email protected]' \
--header 'CVE-API-USER: [email protected]' \
--header 'CVE-API-ORG: education' \
--header 'CVE-API-KEY: <key>'Example response:
{
user: {
username: String,
org_UUID: String,
UUID: String,
active: Boolean,
name: { // first, last, middle, surname, suffix },
authority: {
active_roles: [ADMIN || EMPTY]
}
}
}Secretariat:
A user associated with an Org possessing the Secretariat role can deactivate any Org's users.
Org Admin:
A user with the Org Admin role can only deactivate users for their Org.
General User:
A general user cannot activate or deactivate themselves.
Example request:
curl --location --request PUT 'https://cveawg.mitre.org/api/org/education/user/[email protected]?active=false' \
--header 'CVE-API-USER: [email protected]' \
--header 'CVE-API-ORG: education' \
--header 'CVE-API-KEY: <key>'Example response:
{
user: {
username: String,
org_UUID: String,
UUID: String,
active: Boolean, //(should be false now)
name: { // first, last, middle, surname, suffix },
authority: {
active_roles: [ADMIN || EMPTY]
}
}
}