← FlexAPI Documentation / Reference / Authenticating to SIGNiX via OAuth

Authenticating to SIGNiX via OAuth

Flex API B2B calls can authenticate with an OAuth access token instead of the user ID and password in CustInfo. The flow has three steps: create a token, use the token on your API calls, and refresh it when needed. Available since SIGNiX releases 177 and 178.

Before you start

  • OAuth must be enabled by SIGNiX. Switching to OAuth authentication requires configuration from SIGNiX. Contact SIGNiX to have it set up for your account.
  • Legacy authentication can be restricted. Once you are using OAuth, SIGNiX can also configure your account so that the legacy user ID and password authentication is no longer accepted.
  • Your credentials stay the same. The client_id and client_secret used to create a token are your Client and password, the same values you use in CustInfo.
  • Request only the scopes you need. Each scope limits what the token can do.

Create a token

Send an HTTP POST to the token endpoint with the form parameters below.

ServerToken endpoint
Testhttps://webtest.signix.biz/restservices/oauth2/token
Productionhttps://www.signix.net/restservices/oauth2/token
ParameterValue
grant_typeclient_credentials
client_idYour Client
client_secretYour password
scopeThe scopes you need, as listed below. To request more than one, separate them with a space.

Scopes

  • create:transaction
  • read:transaction
  • update:transaction
  • update:document
  • read:user
  • admin:account: account administration. Required for UpdateNotaryProfile.

The response returns the access token to use on your B2B calls.

Use the token on B2B calls

Pass the access token in the HTTP headers of each B2B call, as a bearer token: Authorization: Bearer YOUR_ACCESS_TOKEN.

The user ID and password are not used when a token is presented, so do not send real values for them. The UserId and Pswd elements are still required in CustInfo, though, so send a placeholder value in each, as shown below.

CustInfo when authenticating with an OAuth token
<CustInfo> <!-- Occurs once only -->

  <!-- Sponsor and Client as usual. -->
  <Sponsor>YOUR_SPONSOR</Sponsor>
  <Client>YOUR_CLIENT</Client>

  <!-- Still required, but not used when an OAuth token is presented in the headers.
       Send a placeholder value, not your real user ID and password. -->
  <UserId>YOUR_PLACEHOLDER</UserId>
  <Pswd>YOUR_PLACEHOLDER</Pswd>

</CustInfo>

Refresh the token

Access tokens are time-limited. When a token expires, or is about to, use the refresh call to renew it, then use the renewed token on your B2B calls.

Testing

A test harness for testing with OAuth is available. Use the test server for all development, and do not submit real documents or real identity information to it.