Skip to main content
Get started integrating your OAuth App with iinked Sign via our OAuth 2.0 authorization code flow.

​
Requesting your client ID and secret

The first step is to request a client id and secret for one of our sandbox instances so that you can get started. We require that you provide one or more redirect URL(s) for the authorization redirect callback to your application. Complete Request Form (iinked Sign)
You can request multiple redirect URLs to be whitelisted. HTTPS is required.Redirect URL ExamplesIf you would like to use Postman’s built in OAuth 2.0 authorization during development: https://oauth.pstmn.io/v1/callback (default)It is also common to include localhost during development: https://localhost/auth/syngrafii (example)Once you have your client id and secret, you can contact support@syngrafi.com directly to open a ticket and request any additional changes.

​
Authorization code flow

iinked Sign provides an OAuth 2.0 authorization code flow (RFC 6749, Section 4.1) with optional PKCE support.

​
Authorizing your application

Direct your user to the connect/authorize URL with the following query parameters:
Authorize URL
https://sandbox.syngrafii.com/connect/authorize
​
response_type
string
required
Use code as a response type.
​
client_id
string
required
Your OAuth App client id.
​
redirect_uri
string
required
One of the redirect URLs you provided when requesting your OAuth App client id and secret. Contact support@syngrafii.com if you need to modify your redirect URL(s).
​
scope
string
For most integrations request profile offline_access organization. If you support OpenID Connect include openid to also receive an id_token (for example: profile openid offline_access organization).
​
state
string
A value returned with the callback to help maintain state between the request and callback and to help prevent CSRF attacks. (optional)
​
nonce
string
When using OpenID Connect, provide a nonce to help prevent replay attacks. (optional)
​
prompt
string
Prompt options to influence the authorization user experience. See values below.
​
code_challenge
string
(Required when using PKCE) Code challenge value.
​
code_challenge_method
string
(Required when using PKCE) Code challenge method (for example: S256).
Authorize URL Example
https://sandbox.syngrafii.com/connect/authorize?client_id=my-client-id&redirect_uri=https%3A%2F%2Flocalhost%3A44319%2Fauth%2Fsyngrafii&response_type=code&scope=profile%20openid%20offline_access%20organization
The user will then be prompted to authorize access for your application, once they have authorized the access, they will be redirected back to your application using the provided redirect_uri query parameter. If the user had previously authorized your application, they will automatically be redirected back to your application.

​
Retrieving tokens

The callback to your application will contain a code query parameter and state query parameter if one was provided with the original request. You must use this code to retrieve your tokens by making a POST request to the connect/token endpoint.
POST
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded
https://sandbox.syngrafii.com/connect/token
client_id:client_secret must be Base64 Encoded
​
grant_type
string
required
Use authorization_code as the grant type.
​
code
string
required
The authorization code returned to your callback. Use this to exchange for tokens.
​
client_id
string
(Only required if the Authorization header is not provided) Your client_id.
​
client_secret
string
(Only required if the Authorization header is not provided) Your client_secret.
Response
{
  "access_token": "XXXX…",
  "refresh_token": "YYYY…",
  "id_token": "ZZZZ…",
  "token_type": "Bearer",
  "expires_in": 1800,
  "scope": "profile openid offline_access organization"
}

​
Using an access token

You can now make requests to the iinked Sign API by adding the access token to Authorization header as a Bearer token.
iinked Sign access tokens are obtained through the OAuth 2.0 authorization process.
Request Header 
Authorization: Bearer <TOKEN>

​
Refreshing an access token

The access token has a short lifetime and must be refreshed by making another POST request to the connect/token endpoint and passing the refresh token.
POST
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded
https://sandbox.syngrafii.com/connect/token
client_id:client_secret must be Base64 Encoded
Request ParameterDescription
grant_typeUse refresh_token as grant type.
refresh_tokenUse the refresh_token returned from the last call.
client_id(Only if Authorization header is not provided) Your client_id.
client_secret(Only if Authorization header is not provided) Your client_secret.
Single Use Refresh Tokens iinked Sign has implemented single use Refresh Tokens. When refreshing the access token, a new refresh token will be returned along with the access token. It is important to replace the previous refresh token with the new one as they will expire 60 seconds after they have been redeemed. This 60 second leeway helps reduce any concurrency issues within your application that may result in using the current refresh token at the same time. Rolling Refresh Tokens When a new refresh token is returned, its lifetime will be also be renewed. Therefore, reauthorization will only be required when applications have not been used for several months.

​
Implementation

​
Common workflow

1

Authorize your application

  • Store refresh token
  • Cache access token
  • Set event notification callback api/v1/events/endpoints/set (if required)
  • Sync organization and members api/v1/organizations/info (if required)
2

Get Access Token

  • Get from cache
  • If expired / not cached
    • Get new tokens using refresh token
    • Store new refresh token
    • Cache new access token
3

Call api/v1/packages/add

Call api/v1/packages/add to add a package.See the Packages add API for more information.

​
Mapping event notifications

If you set an event notification callback endpoint for the organization, you will be notified as packages progress through their signing workflows. To map those events to a specific package you will need to store the organizationId, memberId, and packageId returned from the api/v1/packages/add API call. See the Webhooks setup guide for more information.

​
OAuth configuration

OAuth Endpointssandbox.syngrafii.com used for examples
Authority (OpenID)https://sandbox.syngrafii.com
https://sandbox.syngrafii.com/.well-known/openid-configuration
https://sandbox.syngrafii.com/.well-known/jwks
Authorizehttps://sandbox.syngrafii.com/connect/authorize
Tokenhttps://sandbox.syngrafii.com/connect/token
Revokehttps://sandbox.syngrafii.com/connect/revoke
User Infohttps://sandbox.syngrafii.com/connect/userinfo

​
Response types

Response TypeDescription
codeAuthorization Code Flow

​
Scopes

ScopeDescription
profileRequest access to user’s profile.
openidRequest that an id_token is returned containing the user’s profile.
offline_accessRequest that a refresh_token is returned that can be stored and used to request new access tokens.
organizationRequest access to the organization. Can access profiles and add packages for all organization members. Can also set a callback URL to receive event notifications from the organization. User must be an Organization Administrator to authorize this request.
memberRequest access to the organization member. Can only add packages for this member.

​
Claims

ClaimSource / Description
id_token or connect/userinfo endpointReturned from id_token or connect/userinfo endpoint
subSubject
emailEmail address
given_nameGiven name
family_nameFamily name
s:organizationOrganization ID
s:memberMember ID