Authorize Credential Request 

In the optimised flow the steps to authorise the SignatureApplication and the credential can be combined. 

This is done via a oauth2/authorize (described in Authorize Request) request with scope credential. For this request, the signer must be redirected to the SIGN8 OAuth2 server and first register or login and afterwards identify/ authenticate themselves. 

Example for oauth2/authorize (service authorization): 

Attention: In this step the SignatureApplication can passes one specific credentialID, which should be used or the signatureQualifier. The signatureQualifier specifies, which kind of signature will be created. If the parameter CredentialID is used, the SignatureApplication needs to secure if the credential is valid and assigned to the signatory. Otherwise, the authorization will fail.  

Access Token Credential Request 

Afterwards the SignatureApplication needs to request a credential access token with oauth2/token (described in Access Token Request) to access the API functions.  

If the oauth2/authorise request was called with the signatureQualifier parameter, the response returns the credentialID that will be used in the signature process. 

Example for oauth2/token: 

Get Credential Info 

Optional the SignatureApplication can request further information about the authorized credential with credentials/list (described in Access Token Request). This step can be skipped.  

Example for credentials/info: 

SignHash or SignDoc 

Finally, the SignatureApplication can request a raw PKCS#1 signature via signatures/signHash (described in Sign Hash) with the previously created accessToken. If the SignatureApplication wants to create a CaDES, JaDES or PaDES signature, the signatures/signDoc endpoint should be used.  

Example for signatures/signHash: 

Example for signatures/signDoc: 

Attention: returnValidationInfo can be used to add the validation information to the signature container.

Sign Polling 

If signatures/signHash or signatures/signDoc was called asynchronously (“A”) in operationMode, only a responseID is returned in the response of the signature request. To retrieve the signature object, the SignatureApplication must call signatures/signPolling (described in Sign Polling). 

Example for signatures/signPolling: 

Revoke Access Token 

After a successful signature process, the SignatureApplication can revoke the access tokens to prevent misuse of the tokens. Both access tokens can only be used for one hour. The credential access token can only be used for the maximum number of signatures as previously defined in the numSignatures parameter in the oauth2/authorise request. 

Example for oauth2/revoke: 

​

All Endpoints 

Info 

OAuth2

Authorize Request 

This is the OAuth 2.0 authorization endpoint. This endpoint needs to be opened in a popup or via redirect. 

Attention: the “hashes” needs to be base64 URL-encoded!

Path 

 GET    {{ OAUTH2_URL }}/oauth2/authorize? 

Parameter 

Key		Value	Possible Values
scope	Required	String	service, credential
client_id	Required	String	{{ client_ID }}
redirect_uri	Required	String	{{ redirect_uri }}
code_challenge	Required	String	{{ code_challenge }}
code_challenge_method	Optional	String	S256, S384, S512   default: S256
state	Optional	String	Random string
account_token	Required	String	{{ JWT }}
response_type	Required		code
credentialID	Required   (if scope = credential)	String	{{ credentialID }}
signatureQualifier	Optional   (if scope = credential)	String	{{ signatureQualifier }}
numSignatures	Required   (if scope = credential)	String	1 - x
hashes	Required   (if scope =  credential)	Array of Strings	{{ hashes }}
hashAlgorithmOID	Required   (if scope = credential)	String	2.16.840.1.101.3.4.2.1, 2.16.840.1.101.3.4.2.2, 2.16.840.1.101.3.4.2.3
description	Optional	String	Random string

When no redirect_uri  is passed, we use the first registered redirect URI as default. 

Result  

Code	Message	Cause
302	Found	Found
500	Error	Internal Server Error

302 Found - Code 

 <redirect_uri>/code=…&state=123456 

302 Found - Error 

 <redirect_uri>/error=invalid_request&error_description=<description>

Authorize with Authentication Certificate Request 

This is the OAuth 2.0 authorization endpoint, which can be used for shadow sealing processes.  

To use the endpoint, the seal owner first needs to request an authentication certificate in his OAuth2 user account (under 2FA settings). 

Attention: the “hashes” needs to be base64 URL-encoded

Path 

 POST    {{ OAUTH2_URL }}/oauth2/authorize_tls? 

Authentication 

TLS authentication is required for access to this endpoint. The client must send a valid TLS client certificate issued by SIGN8 and the corresponding key with every request. The connection is only accepted on the server side if the certificate is valid. 

Parameter  

Key		Value	Possible Values
scope	Required	String	service, credential
client_id	Required	String	{{ client_ID }}
redirect_uri	Required	String	{{ redirect_uri }}
code_challenge	Required	String	{{ code_challenge }}
code_challenge_method	Optional	String	S256, S384, S512   default: S256
state	Optional	String	Random string
account_token	Required	String	{{ JWT }}
response_type	Required	String	code
credentialID	Required   (if scope = credential)	String	{{ credentialID }}
numSignatures	Required   (if scope = credential)	String	1 - x
hashes	Required   (if scope = credential)	Array of Strings	{{ hashes }}
hashAlgorithmOID	Required   (if scope = credential)	String	2.16.840.1.101.3.4.2.1, 2.16.840.1.101.3.4.2.2, 2.16.840.1.101.3.4.2.3
description	Optional	String	Random string

When no redirect_uri is passed, we use the first registered redirect URI as default.

Result

Code	Message	Cause
200	Ok	Ok
400	Error	Bad Request
401	Error	Unauthorized
500	Error	Internal Server Error

200 Body 

 { 

    “code”: {{ code }}, 

    (“state”: {{ state }}) 

 } 

Access Token Request 

This is the OAuth2 token endpoint. It is used to obtain an OAuth 2.0 bearer access token from the authorization server by passing the authorization code or refresh token returned by the authorization server after a successful user authentication, along with the client ID and client secret. 

Path 

  POST    {{ OAUTH2_URL }}/oauth2/token 

Header 

Key	Value
Content-Type	application/x-www-form-urlencoded

Parameter 

Key		Value	Possible Values
grant_type	Required	String	authorization_code, refresh_token
code	Required	String	{{ code }}
client_id	Required	String	{{ client_ID }}
client_secret	Optional	String	{{ client_secret }}
redirect_uri	Required	String	{{ redirect_uri }}
refresh_token	Optional	String	{{ refresh_token }}
clientData	Optional	String	{{ clientData }}

The redirect_uri parameter NEEDS to be passed, when it was passed in the “authorize” request. 

Result 

Code	Message	Cause
200	Ok	Ok
400	Error	Bad Request
401	Error	Unauthorized
500	Error	Internal Server Error

200 Body 

 { 

    “access_token”: {{ access_token }} 

    “token_type”: “Bearer”, 

    “expires_in”: 3600, 

   (“credentialID”: {{ credentialID }}) 

 } 

Revoke Access Token 

Revoke an access token or refresh token that was obtained from the authorization server. This method may be used to enforce the security of the remote service. When the signature application needs to terminate a session, it is recommended to invoke this method to prevent further access by reusing the token. 

Path 

   POST    {{ OAUTH2_URL }}/oauth2/revoke  

Header 

Key	Value
Authorization	Bearer {{service_access_token}} OR Bearer {{credential_access_token}}
Content-Type	application/x-www-form-urlencoded

 

Parameter 

Key		Value	Possible Values
token	Required	String	{{ access_token }}
token_type_hint	Optional	String	access_token, refresh_token
client_id	Required	String	{{ client_ID }}
client_secret	Required	String	{{ client_secret }}
clientData	Optional	String	{{ clientData }}

Result

Code	Message	Cause
204	Success	Ok
400	Error	Bad Request
401	Error	Unauthorized
500	Error	Internal Server Error