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.

Update to GET /cve-id Endpoint!

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 1k, the service will now only give 1k of the IDs and include a field to use to request the rest (or the next set of 1k) IDs that fit that query. It's important to note that if your tooling never constructs a query that would result in over 1k 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.

Account Administration

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.

Resetting an API Key

Example request:

curl --location -g --request POST '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>"
}

Updating User 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 POST '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]
        }
    }
}

Getting a List of Users for your Organization

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]
            }
        }
    ]
}

Getting a Specific User

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]
        }
    }
}

Deactivating a User [Org Admin Only]

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]
        }
    }
}