OAuth 2.0

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

string

required

Use code as a response type.

string

required

Your OAuth App client id.

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).

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).

string

A value returned with the callback to help maintain state between the request and callback and to help prevent CSRF attacks. (optional)

string

When using OpenID Connect, provide a nonce to help prevent replay attacks. (optional)

string

Prompt options to influence the authorization user experience. See values below.

Show values

Value	Description
consent	Require the user to consent to the requested scopes even if they have previously consented.
login	Require the user to login again even if they are already authenticated.

string

(Required when using PKCE) Code challenge value.

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

string

required

Use authorization_code as the grant type.

string

required

The authorization code returned to your callback. Use this to exchange for tokens.

string

(Only required if the Authorization header is not provided) Your client_id.

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 Parameter	Description
grant_type	Use refresh_token as grant type.
refresh_token	Use 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

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)

Get Access Token

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

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 Endpoints	sandbox.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`
Authorize	`https://sandbox.syngrafii.com/connect/authorize`
Token	`https://sandbox.syngrafii.com/connect/token`
Revoke	`https://sandbox.syngrafii.com/connect/revoke`
User Info	`https://sandbox.syngrafii.com/connect/userinfo`

Response types

Response Type	Description
code	Authorization Code Flow

Scopes

Scope	Description
profile	Request access to user’s profile.
openid	Request that an id_token is returned containing the user’s profile.
offline_access	Request that a refresh_token is returned that can be stored and used to request new access tokens.
organization	Request 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.
member	Request access to the organization member. Can only add packages for this member.

Claims

Claim	Source / Description
id_token or connect/userinfo endpoint	Returned from id_token or connect/userinfo endpoint
sub	Subject
email	Email address
given_name	Given name
family_name	Family name
s:organization	Organization ID
s:member	Member ID

Getting started

Guides

API

Webhooks

Reference

Requesting your client ID and secret

Authorization code flow

Authorizing your application

Retrieving tokens

Using an access token

Refreshing an access token

Implementation

Common workflow

Authorize your application

Get Access Token

Call api/v1/packages/add

Mapping event notifications

OAuth configuration

Response types

Scopes

Claims

​Requesting your client ID and secret

​Authorization code flow

​Authorizing your application

​Retrieving tokens

​Using an access token

​Refreshing an access token

​Implementation

​Common workflow

Authorize your application

Get Access Token

Call api/v1/packages/add

​Mapping event notifications

​OAuth configuration

​Response types

​Scopes

​Claims

Requesting your client ID and secret

Authorization code flow

Authorizing your application

Retrieving tokens

Using an access token

Refreshing an access token

Implementation

Common workflow

Mapping event notifications

OAuth configuration

Response types

Scopes

Claims