Skip to main content
Plans: Every plan. While the workspace is read-only, uploads are refused with 402. Who: owners and admins create and revoke API tokens; every member can see the token list.
The Pharus API takes SBOMs from your CI pipelines and from Dependency-Track. Each request is authenticated with an API token that belongs to one product family, and each SBOM you send is stored for that family and matched within seconds.

​
Base URL

All endpoints are under https://app.pharussecurity.com/api/v1 and use HTTPS.

​
Authentication

Send the token in the Authorization header:
A token:
  • starts with phr_, followed by 43 letters, digits, - and _, so secret scanners can recognise it;
  • can upload SBOMs to one product family and nothing else;
  • is shown once, when it is created. Pharus stores only a hash, so a lost token has to be replaced.
Never put a token in a URL. Store it as a secret in your CI system, for example as PHARUS_TOKEN.

​
Create a token

1

Open the token page

Go to Settings → API tokens and select Create token. You need at least one product family.
2

Describe the token

Enter a Name, after the pipeline that uses it, for example “GitHub Actions – gateway-g3”. Pick the Product family and when it Expires: In 30 days, In 90 days, In 1 year (the default) or Never.
3

Copy it

Select Create token. Pharus shows the token once, under Copy your token: copy it and add it to your pipeline as a secret. Open pipeline snippets takes you to ready-made steps on the SBOMs page.
Create one token per pipeline, so you can revoke a single CI job without touching the others. The token’s name shows on each SBOM it sends, under Sent by, and in the audit trail. The list under Settings → API tokens shows each token’s Name, Product family, the first characters of the Token, when it was Created and by whom, when it was Last used, when it Expires and its Status: Active, Expired or Revoked.

​
Revoke or rotate a token

To revoke a token, select Revoke token on its row and confirm. Pipelines using it get 401 from then on. This can’t be undone. To rotate a token, create a new one for the same family, replace the secret in your pipeline, check that the new token’s Last used changes, then revoke the old one. A token also stops working when it expires, and while its product family is archived. Archived families’ tokens leave the list; they work again if the family is restored, unless they have expired or been revoked meanwhile.

​
Requests

  • Send POST requests over HTTPS.
  • The body is the SBOM file itself, not a form upload and not wrapped in JSON. With curl, use --data-binary.
  • Gzip the body and send Content-Encoding: gzip. A request may be at most 4 MB as sent, and 50 MB once decompressed.
  • Optional X-Pharus-* headers add the product version and pipeline details. See upload an SBOM.

​
Responses

Responses are JSON. A successful upload returns 202 Accepted for a new SBOM and 200 OK when Pharus already has the same file for that family, so a retry is safe. Errors have this shape:
error is a stable code you can test for. message is an English explanation for your CI log. detail is only there when Pharus has more to say.

​
Status codes

The Dependency-Track endpoint has a few codes of its own. See Dependency-Track.

​
402 when the workspace is read-only

When the free trial or the subscription ends without a new one, the workspace moves to Free and becomes read-only. When the owners close it, it is closed. In both cases every upload gets 402 with billing_lapsed, and the message says which: a Free workspace needs an owner to subscribe under Settings → Billing, and a closed one needs an owner to reopen it in company settings. A 402 makes a CI step that uses curl --fail-with-body fail visibly, instead of the SBOM being dropped without a trace. See billing.

​
Rate limits

Each token can make 60 requests per hour, counted together across POST /api/v1/sboms and the Dependency-Track endpoint. Every authenticated request counts, whether or not it stores anything: duplicates, rejected files and Dependency-Track test notifications too. Past the limit, Pharus answers 429 with rate_limited and a Retry-After header with the number of seconds to wait.

Upload an SBOM

Dependency-Track

GitHub Actions

SBOMs in the app