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"
}