> ## Documentation Index
> Fetch the complete documentation index at: https://about.sendforsign.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication
> Learn how to authenticate your API requests to the SFS API platform.
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](https://oauth.net/2/),
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.
```bash cURL theme={null}
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):
```bash JSON theme={null}
{
"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:
```bash cURL theme={null}
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.
```bash JSON theme={null}
{
"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:
```bash cURL theme={null}
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):
```bash JSON theme={null}
{
"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:
```bash cURL theme={null}
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.
```bash JSON theme={null}
{
"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.
```bash cURL theme={null}
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": "Contract text
"
}
}
}'
```
```bash cURL theme={null}
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": "Contract text
"
}
}
}'
```