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

Credentials

Octet Browser uses four 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
Edge signing key A 32-byte key in base64, created on the edge host. Its public half and kid appear in the edge's startup log Your edge's EDGE_SIGNING_KEY setting Until you revoke it You, on the edge host, registered in the Octet portal
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 signing key signs each session your edge forwards, and Octet checks that signature against the public keys registered for your 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, the edge's private key and the edge's signing key are secrets. The client certificate and the signing key's public half are not.

In the Octet portal, each Octet Browser license has two tabs. Edge configuration is for your edge server, with Certificates for its client certificates and Signing keys for its signing keys. Verdict API is for your backend, with Read tokens.

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 configuration tab, then Certificates. The page 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 configuration tab, under Certificates, 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 configuration tab, under Certificates.
  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 configuration tab, under Certificates.

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

Register an edge signing key

The signing key is created on the edge host and never leaves it. Octet sees only its public half:

  1. On the edge host, create the key with openssl rand -base64 32, and set it as EDGE_SIGNING_KEY in the edge's environment file.
  2. Restart the edge. Its startup log shows S2 signing on: kid=… ed25519 public key=….
  3. In the portal's Edge configuration tab, under Signing keys, paste the kid and the public key, and select Register key.

The commands are in Deploy the Edge. Only portal users with the owner or admin role can register or revoke signing keys, and only while the license is active. A license can have at most 3 active signing keys at a time. A signing key doesn't expire.

Rotate an edge signing key

Because a license can hold 3 active signing keys, you can rotate with no gap:

  1. Create a new key on the edge host, set it as EDGE_SIGNING_KEY, and restart the edge.
  2. Register the new kid and public key from the startup log.
  3. Confirm that the license check still returns unsealed_bundle.
  4. Revoke the old key in the Edge configuration tab, under Signing keys.

Sessions the edge forwards between steps 1 and 2 carry a signature from a key Octet doesn't know yet. Once Octet requires edge signatures, it refuses those sessions with 401 and edge_key_unknown, so register the key straight after the restart.

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 Verdict API tab, then Read tokens.
  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 Verdict API tab, under Read tokens.

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 Verdict API tab, under Read tokens. 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 configuration tab, under Certificates, 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.
  • Edge signing key: revoke it in the portal's Edge configuration tab, under Signing keys, when an edge host is retired or the key may have been copied. Within about a minute Octet stops recognising it. Once Octet requires edge signatures, sessions signed with it get 401 and edge_key_unknown.

Keep credentials out of the browser

  • Never put a token, the edge's private key or its signing 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 and signing 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.