--- title: GCVE-BCP-14 - Interoperable Identifier Allocation API ---

Interoperable Identifier Allocation API

Image

  • Version: 0.1
  • Status: Draft (for Public Review)
  • Date: 2026-11-06
  • Authors: GCVE Working Group
  • BCP ID: BCP-14

This guide is distributed and available under CC-BY-4.0.

Copyright (C) 2026 GCVE Initiative.

Introduction

Vulnerability identifiers are allocated by different authorities and software platforms, often through implementation-specific interfaces. This BCP defines a minimal, interoperable HTTP API for requesting identifiers from an authorised allocation service. It allows independent tools, including Vulnerability-Lookup, to expose or consume a common allocation interface.

The API applies to GCVE Numbering Authorities (GNAs), CVE Numbering Authorities (CNAs), and other identifier schemes. It does not establish allocation authority, change an identifier scheme's rules, or require a publicly accessible service.

Allocation Principles

  • An authority is the organisation or delegated entity entitled to allocate identifiers within a given namespace (e.g., GCVE, CVE, or another scheme).
  • Implementations MUST verify that the caller is authorised to request allocation on behalf of the specified authority. An API provider MUST NOT issue identifiers outside its delegated authority.
  • Allocated identifiers MUST be unique according to the rules of their namespace and MUST NOT be reassigned, even if the corresponding record is never published.
  • Allocation or reservation MUST NOT imply publication, disclosure, or validation of a vulnerability.
  • GCVE identifiers MUST follow GCVE-BCP-04. Other schemes retain their own allocation policies and identifier formats.

HTTP API

A conforming HTTP service MUST expose the following operation relative to its documented API base URL:

POST /api/id-allocation/v1/allocations

Requests and successful responses MUST use JSON (application/json). The request fields are:

| Field | Requirement | Description | |---|---|---| | namespace | MUST | Identifier scheme, e.g., GCVE or CVE. | | authority.type | MUST | Authority category, e.g., GNA, CNA, or a scheme-specific value. | | authority.id | MUST | Identifier of the responsible authority, represented as a string. | | count | MAY | Positive number of identifiers requested; defaults to 1. | | parameters | MAY | Scheme-specific allocation options, e.g., year. |

Example: GCVE Allocation

Request:

POST /api/id-allocation/v1/allocations HTTP/1.1
Content-Type: application/json
Idempotency-Key: example-request-123

{
  "namespace": "GCVE",
  "authority": { "type": "GNA", "id": "1" },
  "count": 2,
  "parameters": { "year": 2026 }
}

Successful response (201 Created):

{
  "namespace": "GCVE",
  "authority": { "type": "GNA", "id": "1" },
  "identifiers": ["GCVE-1-2026-0042", "GCVE-1-2026-0043"],
  "allocated_at": "2026-11-06T13:00:00Z"
}

On success, the response MUST contain namespace, authority, identifiers (an array containing exactly count distinct allocated IDs), and allocated_at (an RFC 3339 timestamp). Implementations MAY add fields without changing these semantics.

A CNA can use the same operation with "namespace": "CVE" and "authority": {"type": "CNA", "id": "<CNA identifier>"}, provided the service is authorised to allocate CVE identifiers through the applicable CVE infrastructure.

Reliability and Errors

  • A client SHOULD send an Idempotency-Key header. Within a documented retention period, a server MUST return the same allocation for the same authenticated caller, namespace, authority, key, and request body, rather than issue new identifiers. Reuse of a key with a different request body in the same scope MUST be rejected.
  • Allocation MUST be safe under concurrent requests. A successful response MUST NOT contain duplicate or previously allocated identifiers.
  • Servers SHOULD use standard HTTP errors: 400 (invalid request), 401 (unauthenticated), 403 (unauthorised authority), 409 (conflict), 429 (rate limit), and 503 (allocation service unavailable). Errors SHOULD include a machine-readable code and a human-readable message.
  • A server MAY restrict batch sizes or reject unsupported scheme-specific parameters; these limits SHOULD be documented.

Security and Deployment

This is potentially an administrative API. Authentication mechanisms, user roles, delegation procedures, rate limits, audit retention, hosting arrangements, and public or private exposure are left to the implementer and the relevant numbering authority. Implementations MUST protect allocation requests in transit, enforce authority-scoped access control, and maintain an auditable allocation history. No public or unauthenticated allocation endpoint is required.

Interoperability

This BCP standardises the allocation interface, not the backing database, numbering algorithm, vulnerability publication API, or governance of a numbering scheme. An implementation MAY proxy an existing authority service or wrap internal allocation functions, as long as it preserves the specified request and response semantics.

GCVE registry metadata may describe an authority's allocation interface. Since the existing gcve_allocation field can also reference a human-facing interface, API implementers SHOULD document the BCP-14 API base URL explicitly rather than assume that every such URL implements this profile.

References