API authentication and integration
Learn how to generate access tokens for authenticating with the Sovos Signer API and managing token expiration.
To access the Signer API services securely, users must complete an authentication flow. This process involves the following components.
Step 1: Get Sovos credentials
To access Sovos Signer services, contact the Professional Services team. They will provide your client_id, client_secret, and all the information you need to access Sovos environments.
Step 2: Obtain an ID token
-
openid -
profile, including thecredentialandbirthdateclaims. -
email -
phone
https://accounts.trust.sovos.com/oauth2/auth?response_type=code&client_id={{client_id}}&state=12345678901234567890&scope=openid%20profile%20birthdate%20email%20phone%20credential%20offline%20offline_access&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&code_challenge={{code_challenge}}&code_challenge_method=S256&acr_values=urn:acr:faceThis first request initiates the user authentication flow that you must complete to connect to the Sovos environment. Use the generated id_token in the following steps, as it serves to authenticate and identify the users involved in the signing process.
Step 3: Obtain an access token
https://accounts.trust.sovos.com/oauth2/token endpoint. This request authenticates the integration client and generates the access_token. To do so, you must include:-
grant_type:client_credentials -
audience:signer.trust.sovos.comaudienceis the resource/server that receives the access token. You need to validate the 'audience' claim in the token to ensure that the received token is intended for the accessed resource.-
The
audienceparameter is used during the token exchange.
-
Configure
token_endpoint_auth_methodto beclient_secret_basicto enable the token exchange.
Cache this token so it can be reused during its validity period for the creation of multiple envelopes.
Step 4: Send API requests
Use the OAuth tokens to authorize requests to the Signer API endpoints.
You can use API testing tools like Postman to authenticate and validate API requests. Define the OAuth token as an environment or global variable, or set directly in the Authorization header. Alternatively, you can use cURL by including the token in a request header for command-line-based testing.
OAuth tokens are valid for 60 minutes. After expiration, you must generate a new token.