Certificate assertion

The recommended way to authenticate API clients. Your client proves its identity by signing a short-lived JWT — the client assertion — with a private key you generate and keep; Scalepoint verifies the signature against the public key registered for your account. No secret is ever transmitted or shared.

This is the standard private_key_jwt method (OpenID Connect Core §9, RFC 7523). The helper libraries implement it end to end, and any conforming OAuth 2.0 library works too — the rest of this page is what Scalepoint specifically requires.

Generate a key pair

A self-signed certificate is fine: Scalepoint pins your registered public keys directly to your account instead of relying on certificate authorities. Use a 2048-bit or stronger RSA key.

With OpenSSL:

openssl req -x509 -newkey rsa:2048 -noenc -subj "/CN=yourcompany-scalepoint-client" -days 730 -keyout client.key -out client.crt

With PowerShell:

$cert = New-SelfSignedCertificate -Subject "CN=yourcompany-scalepoint-client" -CertStoreLocation cert:\CurrentUser\My -KeyAlgorithm RSA -KeyLength 2048 -KeySpec Signature -KeyExportPolicy Exportable -NotAfter (Get-Date).AddYears(2)
Export-Certificate -Cert $cert -FilePath client.crt

The private key stays in the certificate store; client.crt holds only the public certificate.

With Java keytool (producing the keystore the Java helper library consumes):

keytool -genkeypair -keyalg RSA -keysize 2048 -alias authkey -validity 730 -dname "CN=yourcompany-scalepoint-client" -keystore keystore.jks
keytool -exportcert -alias authkey -keystore keystore.jks -file client.crt

The private key stays where your backend runs; only the certificate (the public part) is shared.

Register the certificate

Send the certificate file (client.crt) to Scalepoint during onboarding and we register it to your client. Several certificates can be registered at once, so you can roll to a new key without downtime: register the new certificate, switch your client to the new key, then have the old one removed.

Token request

POST to the token endpoint, form-encoded:

Parameter	Value
grant_type	client_credentials
scope	the scopes you need, space-separated
client_assertion_type	urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion	the signed JWT described below

The client assertion

Sign the JWT with your private key using RS256. Scalepoint requires:

Claim	Requirement
iss, sub	both your client id, and they must match
aud	the token endpoint URL of the environment, for example https://accounts.scalepoint.com/connect/token
jti	a unique random value per request — a reused value is rejected, which is what prevents replay
exp	required; keep it short (about a minute), the assertion is used exactly once. Clock skew of up to 5 minutes is tolerated

No other claims or JOSE headers are required. Example payload:

{
  "iss": "future_insurance",
  "sub": "future_insurance",
  "aud": "https://accounts.scalepoint.com/connect/token",
  "jti": "35bc88e8-e61d-4aa1-8d46-4aed1798da2e",
  "iat": 1767950000,
  "exp": 1767950060
}