Quickstart

Summary

This guide takes you from client certificate to a submitted advisory in three requests.

Before you begin

You need:

• the client certificate issued to your organization, either as a certificate and key pair (client.crt, client.key) for curl, or as a PKCS#12 bundle (client.pfx) for PowerShell
• an OAuth 2.0 client ID and secret
• the advisory:write and advisory:read scopes

Every request uses mutual TLS. See Authentication.

On Windows, use the PowerShell tab. The curl that ships with Windows and Git for Windows uses Schannel, which cannot load a .crt and .key pair.

The PowerShell examples work in Windows PowerShell 5.1 and PowerShell 7. Run all three steps in the same session: later steps reuse $cert, $token, and $headers.

1. Get an access token

Request a token with the client credentials grant. The token is bound to the certificate you connect with.

bash

curl --cert client.crt --key client.key \
  -X POST https://auth.embargogate.example/oauth2/token \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<CLIENT_ID>" \
  --data-urlencode "client_secret=<CLIENT_SECRET>" \
  --data-urlencode "scope=advisory:write advisory:read"

The response contains an access_token. Use it in the next steps.

PowerShell

$certPath = (Resolve-Path -Path '.\client.pfx').Path
$cert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2 -ArgumentList $certPath, '<PFX_PASSWORD>'

$body = @{
    grant_type    = 'client_credentials'
    client_id     = '<CLIENT_ID>'
    client_secret = '<CLIENT_SECRET>'
    scope         = 'advisory:write advisory:read'
}
$response = Invoke-RestMethod -Method Post -Uri 'https://auth.embargogate.example/oauth2/token' -Certificate $cert -Body $body
$token = $response.access_token

Invoke-RestMethod sends a hashtable body as form data. Resolve-Path is needed because .NET resolves relative paths against the process directory, not your current PowerShell location.

2. Submit an advisory

Send an OpenVEX document to POST /advisories.

bash

curl --cert client.crt --key client.key \
  -X POST https://api.embargogate.example/v1/advisories \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d @advisory.json

PowerShell

$headers = @{ Authorization = "Bearer $token" }
Invoke-RestMethod -Method Post -Uri 'https://api.embargogate.example/v1/advisories' -Certificate $cert -Headers $headers -ContentType 'application/json' -InFile '.\advisory.json'

For the contents of advisory.json, see the sample OpenVEX submission.

A successful request returns 201 Created with the advisory ID. The advisory starts in the SUBMITTED state.

3. Check the advisory

bash

curl --cert client.crt --key client.key \
  "https://api.embargogate.example/v1/advisories/<ADVISORY_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

PowerShell

$advisoryId = '<ADVISORY_ID>'
Invoke-RestMethod -Uri "https://api.embargogate.example/v1/advisories/$advisoryId" -Certificate $cert -Headers $headers

The response shows the current state. The triage team moves it to VERIFIED or REJECTED. To be notified when that happens instead of polling, register a webhook.

Next steps

• Core concepts: how an advisory moves through its lifecycle
• Errors: what to do when a request fails