Authentication

The SFS API offers industry-standard security controls for connecting to its platform, submitting, storing, and retrieving data from SFS data servers, and conducting various business operations with this data.

​

API security key concepts

The SFS API platform adheres to several principles to uphold the integrity and security of data:

• Secure Data Transmission: All API requests to the SFS API platform must be made via HTTPS. Attempts to make calls over plain HTTP will be unsuccessful.
• Bearer Token Authentication: Each API request must authenticate using a Bearer token. This token is generated by SFS using the provided API Key and Secret. This authentication method aligns with OAuth 2.0 standards, the recognized protocol for API authorization. When an API request is received, SFS checks whether the bearer of the token is valid and has not expired.

​

API Key and Secret

SFS’s token mechanism complies with the OAuth 2.0 standard, which allows for the generation of short-lived tokens. These tokens, with customizable lifespans, are more secure than longer-lasting API keys and help reduce the risk of damage from potential leaks.

To generate tokens for the SFS API, platform developers must first log into their account on the SFS Portal, where they can access existing API Keys and Secret.

​

Creating platform tokens

To create a new token for accessing the SFS API, first you need to call POST /api/token with the request body containing the apiKey and Secret values you obtained in the previous step.

The /api/token endpoint does not require any authentication headers, which is in line with the OAuth 2.0 standard.

curl -X POST 'https://api.sendforsign.com/api/token' \
     -H 'Content-Type: application/json' \
     -d '{
         "data": {
            "action": "create",
            "apiKey": "YOUR_API_KEY",
            "secret": "YOUR_SECRET"
         }
}'

The successful 201 Created response contains the access_token and its validity time (in seconds):

{
  "access_token": "123456789...",
  "token_type": "Bearer",
  "expires_in": 1800
}

​

Revoking platform tokens

Tokens generated within the SFS API platform have an auto-expiry based on the specified expires_in value (in seconds). Nevertheless, in certain cases you may want to explicitly revoke an active token, such as when a client logs out from your application.

To revoke a token, call POST /api/token with a request body containing the revoke action, and specify the platform Bearer token in the header:

curl -X POST 'https://api.sendforsign.com/api/token' \
     -H 'Authorization: Bearer 123456789' \
     -H 'Content-Type: application/json' \
     -d '{
        "action": "revoke"
     }'

A 201 OK response indicates that the specified token has been revoked successfully.

{
    "code": 201,
    "message": "Token revoked"
}

​

Creating client tokens

A Client token is a specific token issued for an individual platform client. These tokens allowing actions to be directly linked to specific client within your platform.

To generate a client token, call POST /api/token, and specify the Key of this client in clientKey request field, and specify the platform Bearer token in the header:

curl -X POST 'https://api.sendforsign.com/api/token' \
     -H 'Authorization: Bearer 123456789' \
     -H 'Content-Type: application/json' \
     -d '{
        "action": "create",
        "clientKey": "YOUR_CLIENT_KEY"
     }'

The successful 201 Created response contains the access_token and its validity time (in seconds):

{
  "access_token": "123456789...",
  "token_type": "Bearer",
  "expires_in": 1800
}

​

Revoking client tokens

Tokens generated within the SFS API platform have an auto-expiry based on the specified expires_in value (in seconds). Nevertheless, in certain cases you may want to explicitly revoke an active token, such as when a client logs out from your application.

To revoke a token, call POST /api/token with a request body containing the revoke action and the client access token, and specify the platform Bearer token in the header:

curl -X POST 'https://api.sendforsign.com/api/token' \
     -H 'Authorization: Bearer 123456789' \
     -H 'Content-Type: application/json' \
     -d '{
        "action": "revoke",
        "access_token": "eyJ0eXAiOiJKV1QiLCJhb..."
     }'

A 201 OK response indicates that the specified token has been revoked successfully.

{
    "code": 201,
    "message": "Token revoked"
}

​

Authentication for testing purposes

Although we always recommend using Sendforsign’s token mechanism to access our infrastructure, there is an alternative way to send API calls and render Sendforsign’s components without the need to generate tokens.

You can use a combination of an API Key (in the request header) and a Client Key (in the request body) to achieve the same result as using the access token.

Compare the two requests below; both will result in creating a new contract in Sendforsign’s infrastructure. In the first case, you will need to use only your Bearer Access Token, and in the second case, you can use your X-Sendforsign-Key API key in the header and your Client Key in the request body.

curl -X POST 'https://api.sendforsign.com/api/contract' \
     -H 'Authorization: Bearer 123456789' \
     -H 'Content-Type: application/json' \
     -d '{ 
         "data": {
         "action": "create",
            "contract": {
               "name": "New contract",
               "value": "<p>Contract text</p>"
                  }
               }
}'

curl -X POST 'https://api.sendforsign.com/api/contract' \
     -H 'X-Sendforsign-Key: YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{ 
         "data": {
         "action": "create",
         "clientKey": "YOUR_CLIENT_KEY",
            "contract": {
               "name": "New contract",
               "value": "<p>Contract text</p>"
                  }
               }
}'