# auth.md

CVD Portal authenticates agents with a bearer API key that a company administrator creates in the dashboard. Anonymous agents need no credential to file a vulnerability report through a company portal. No OAuth authorization server exists.

## Key takeaways

- Two agent audiences exist. A researcher agent files vulnerability reports. A company agent manages that company's own compliance records.
- A researcher agent needs no credential to submit a report through a company portal at `https://<company>.cvdportal.com`.
- A company agent needs a bearer API key. Only a signed-in administrator on the Enterprise plan can create one.
- The only supported credential method is the HTTP `Authorization: Bearer <key>` header.
- No endpoint issues a credential to an unauthenticated caller, so no registration URI is advertised here.

## Which agents this applies to

CVD Portal is a compliance platform for manufacturers that sell products with digital elements into the European Union. Two machine surfaces are open to agents.

The public portal accepts vulnerability reports about a company's products. A security researcher, or an agent acting for one, is the audience.

The company API and the Model Context Protocol server read and write that company's own records. Vulnerability reports, products, Software Bill of Materials documents, scan findings and compliance status are available. An agent acting for the company that owns the records is the audience.

## Anonymous vulnerability submission

No credential is required. Submit the report through the company's public portal.

| Item | Value |
|---|---|
| Method | Anonymous. No credential |
| Portal | `https://<company>.cvdportal.com` |
| Report form | `https://<company>.cvdportal.com/submit` |
| Disclosure policy | `https://<company>.cvdportal.com/.well-known/security.txt` |

Read the company's `security.txt` file first. The file names the accepted languages, the preferred report format and the disclosure policy that applies.

A company agent that holds an API key with the `submissions:write` scope can submit the same report to `POST https://cvdportal.com/api/v1/vulnerabilities` instead.

## Authenticated company API

### How to get a credential

Credential creation is gated to a human administrator. An agent cannot self-register.

1. An administrator of the company signs in to the dashboard.
2. The administrator opens `https://cvdportal.com/settings/api-keys`.
3. The administrator creates a key, then selects the scopes and the optional source address allowlist that the agent needs.
4. The dashboard shows the key one time. The administrator gives that value to the agent.

The dashboard page calls `POST https://cvdportal.com/api/settings/api-keys`. That endpoint needs an authenticated administrator session, so an agent cannot call it. No public registration endpoint exists.

| Item | Value |
|---|---|
| Provisioning surface | `https://cvdportal.com/settings/api-keys` |
| Provisioning endpoint | `POST https://cvdportal.com/api/settings/api-keys` |
| Caller | Signed-in administrator. Session authenticated |
| Required plan | Enterprise |
| Required role | Administrator |

### How to send the credential

Send the key in the HTTP `Authorization` header with the `Bearer` prefix. No other method is supported. A query parameter, a cookie and a request body field are all refused.

```http
GET /api/v1/vulnerabilities HTTP/1.1
Host: cvdportal.com
Authorization: Bearer <key>
```

The same key authenticates the Model Context Protocol server at `https://cvdportal.com/api/mcp`. Each tool checks its own scope against the key.

| Item | Value |
|---|---|
| Credential type | Bearer API key |
| Header | `Authorization: Bearer <key>` |
| Key format | 64 lowercase hexadecimal characters |
| REST base | `https://cvdportal.com/api/v1` |
| MCP endpoint | `https://cvdportal.com/api/mcp` |
| Machine-readable REST specification | `https://cvdportal.com/openapi.json` |

### Scopes

An administrator selects the scopes when the key is created. A request outside the key's scopes returns HTTP 403.

| Scope | Grants |
|---|---|
| `read` | Read vulnerabilities, products, compliance & SBOM metadata |
| `submissions:write` | Submit vulnerability reports |
| `products:write` | Create and update products |
| `sbom:write` | Push SBOMs from CI/CD |
| `sarif:write` | Push SARIF scan findings |
| `webhooks:write` | Register webhooks |
| `gdpr:export` | Export all company data (DSAR) |

A key created with no scopes is unrestricted. That behaviour exists so keys issued before the scope model keep working. Ask the administrator for the narrowest scope set the task needs.

### Limits and lifecycle

| Item | Value |
|---|---|
| Rate limit | 100 requests per 60 seconds, per key |
| Default expiry | 365 days |
| Maximum expiry | 3650 days |
| Source address allowlist | Optional. Set by the administrator |
| Rotation | The administrator rotates the key. Rotation issues a new value and stops the old one |
| Revocation | The administrator deletes the key |

An expired, revoked or suspended key returns HTTP 401. A key used from an address outside its allowlist returns HTTP 403. An unresolvable client address is refused whenever an allowlist is set.

Every use of a key is recorded in the company's audit log.

## OAuth metadata

CVD Portal runs no OAuth authorization server. The following documents are therefore not published, and an agent must not wait for them.

- `/.well-known/oauth-protected-resource`
- `/.well-known/oauth-authorization-server`

Bearer API keys are the whole credential model. These machine-readable documents describe the surfaces that do exist.

| Document | Purpose |
|---|---|
| `https://cvdportal.com/openapi.json` | OpenAPI specification for the version 1 REST API |
| `https://cvdportal.com/.well-known/api-catalog` | RFC 9727 linkset to the specification, the documentation and the status endpoint |
| `https://cvdportal.com/.well-known/agent-skills/index.json` | Agent skill descriptions for this platform |
| `https://cvdportal.com/llms.txt` | Index of the public content corpus |

## Contact

Write to security@cvdportal.com for a question about this document or about credential handling. Read https://docs.cvdportal.com/cvd/api-overview for the developer guide, and https://docs.cvdportal.com/cvd/mcp-server for the Model Context Protocol server.

Report a vulnerability in CVD Portal itself through `https://cvdportal.com/.well-known/security.txt`.

Last updated: 2026-08-25