Authorize

account_token

account_token is mandatory for service-scope authorization (i.e. the first authorize call for the first QR code).

account_token is to be built from account_id, as per CSC 1.0.4.0 spec, section 8.3.1 Restricted access to authorization servers: https://cloudsignatureconsortium.org/wp-content/uploads/2020/01/CSC_API_V1_1.0.4.0.pdf

The account_token parameter is based on a JSON Web Token (JWT), defined as follows, according to the RFC 7519:

account_token = base64UrlEncode(<JWT_Header>) + "." + base64UrlEncode(<JWT_Payload>) + "." +
base64UrlEncode(<JWT_Signature>)

Components of the above are defined as:

Header:

<JWT_Header> = {
"typ": "JWT",
"alg": "HS256"
}

Payload:

<JWT_Payload> = {
"sub": "<Account_ID>",
"iat": <Unix_Epoch_Time>,
"jti": "<Token_Unique_Identifier>", "iss": "<Signature_Application_Name>", "azp": "<OAuth2_client_id>"
}

Signature:

<JWT_Signature> = HMACSHA256(
base64UrlEncode(<JWT_Header>) + "." +
base64UrlEncode(<JWT_Payload>),
SHA256(<OAuth2_client_secret>)
)

JWT signature within account_token

Note regarding JWT signature: the secret must be passed in as a binary digest of the SHA256 hash of the client secret (jwt_secret=sha256(client_secret).digest()).

Please make sure the JWT conforms to its spec (RFC 7519) (pay particular attention to urlsafe-base64 encoding - see: https://datatracker.ietf.org/doc/html/rfc4648#section-5).

Please also make sure the JWT signature within JWT (JWS) conforms to JWS spec (RFC 7515). Internally, it is an HMAC, but the encoding is important.

You can use the online tool https://jwt.io to validate the format of your JWT and the JWS within JWT (you don't need to put in your client_secret, just put in your token so that the tool will tell you whether it's correctly encoded, including its signature).

Batch signing

/oauth2/authorize uses GET method, so it doesn't handle long query strings well. If you want to sign more than 10 hashes, it is recommended to provide hashes before authorising credentials using optional Credentials Hashes endpoint. In this case, hash param should be removed from /oauth2/authorize call since it has precedence over hashes provided using /credentials/hashes.

Note: Number of hashes you can sign in single request depends on you subscription plan.

Additional notes

Note regarding state parameter: this is an optional parameter that you can pass to the authorize endpoint. If you do, it will be returned back to you after the eventual redirect (redirect to success or error). Note that it will not be returned after early error failure (e.g. client_id not found).