Docs/Octet Browser/Guides/Credentials
MarkdownAsk ChatGPT ↗Ask Claude ↗

Credentials

Octet Browser uses three credentials. None of them may reach the browser.

Credential Looks like Goes in Lifetime Issued by
License token octet_live_v4.public.… Your edge's LICENSE setting 365 days Octet, by email
Edge client certificate octet-edge-<license ID>.crt, with a private key that stays on the edge host Your edge's EDGE_CLIENT_CERT_FILE and EDGE_CLIENT_KEY_FILE settings 397 days You, in the Octet portal, from a certificate request you create
Read token octet_read_v4.public.… Your backend's Authorization header 30, 90, 180 or 365 days You, in the Octet portal

The license token lets your edge send sessions to Octet. The client certificate identifies your edge on its mutual TLS connection to Octet, and is bound to your license: Octet refuses a session whose client certificate belongs to another license. The read token lets your backend fetch the verdicts for those sessions. A read token reads only the verdicts that arrived under its own license.

The license token, the read token and the edge's private key are secrets. The client certificate itself is not.

In the Octet portal, each Octet Browser license has two tabs. Edge certificates is for your edge server. Read tokens is for your backend.

Get a license token

  1. Apply at browser.octetproof.com/signup.
  2. Octet reviews the application. When it is approved, Octet emails your license token and a link to the Octet portal.
  3. Put the token in your edge's environment as LICENSE. See Deploy the Edge.

The license token is valid for 365 days from the day it is issued. Ask Octet for a new one before it expires, at developer@octetproof.com.

Get the edge's client certificate

The private key is created on the edge host and never leaves it. Octet sees only a certificate request:

  1. Sign in to the Octet portal at api.octetproof.com/portal/sign-in, open your Octet Browser license and select the Edge certificates tab. The tab shows your license ID, a lowercase UUID, and the commands with it filled in.
  2. On the edge host, create a private key and a certificate request whose common name is exactly your license ID.
  3. In the Edge certificates tab, paste the request, client.csr, or choose the file, and issue the certificate.
  4. Download the certificate, octet-edge-<license ID>.crt. It is valid for 397 days. Install it next to the key.

The commands are in Deploy the Edge. Only portal users with the owner or admin role can issue or revoke edge certificates, and only while the license is active. Every portal user can see and download them.

Each edge host gets its own key and certificate, all with your license ID as the common name. A license can have at most 3 live edge certificates at a time.

The key must be ECDSA P-256 or P-384, or RSA of 2048 bits or more. The portal refuses a request with any other key, or with a common name other than your license ID.

Renew an edge client certificate

Because a license can hold 3 live edge certificates, you can renew with no gap:

  1. Create a new key and certificate request on the edge host, as for the first certificate.
  2. Issue and download the new certificate in the Edge certificates tab.
  3. Install it, point EDGE_CLIENT_CERT_FILE and EDGE_CLIENT_KEY_FILE at the new files, and restart the edge.
  4. Confirm that the license check still returns unsealed_bundle.
  5. Revoke the old certificate in the Edge certificates tab.

Renew before the old certificate expires. An expired certificate gets 401 with "reason":"client_cert_required".

Create a read token

  1. Sign in to the Octet portal at api.octetproof.com/portal/sign-in with the email address your license was issued to.
  2. Open your Octet Browser license and select the Read tokens tab.
  3. Choose a lifetime of 30, 90, 180 or 365 days. The default is 90.
  4. Create the token and copy it straight into your backend's secret store. The portal shows it only once.

Only portal users with the owner or admin role can create or revoke read tokens, and only while the license is active. A license can have at most 5 live read tokens at a time.

Rotate a read token

Because a license can hold 5 live read tokens, you can rotate with no gap:

  1. Create a new read token.
  2. Deploy it to your backend.
  3. Confirm that verdict fetches succeed with the new token.
  4. Revoke the old token in the Read tokens tab.

Rotate before the old token expires. An expired read token gets 401 with "error": "expired".

Revoke a credential

  • Read token: revoke it in the portal's Read tokens tab. Octet refuses it within minutes.
  • License token: email developer@octetproof.com. Octet revokes it and issues a new one. Once the old token is revoked, your edge's requests get 401 until you deploy the new one.
  • Edge client certificate: revoke it in the portal's Edge certificates tab when an edge host is retired or its key may have been copied. Octet refuses it within about a minute, with 403 and client_cert_revoked. Your other certificates and your license keep working.

Keep credentials out of the browser

  • Never put a token or the edge's private key in page code, the collector's configuration, a URL, or a client-side bundle.
  • Store the tokens in your secret manager and pass them to the edge and backend as environment variables. Keep the edge's private key on the edge host, readable only by the edge's service user.
  • Don't send tokens to Octet support. Quote the sessionRef and the time of the request instead.