---
title: "Authentication"
url: "https://docs.signnow.com/docs/authentication"
type: "page"
section: "Documentation"
slug: "authentication"
---
# Authentication
## About authentication
SignNow API relies on the [OAuth 2.0 protocol](https://oauth.net/2/) for authorization. To authorize API requests, you need a basic authorization token and an access token (bearer token).
> In this article, *access token* and *bearer token* refer to the same thing and are used interchangeably.
| Basic authorization token | Access token |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Base64 encoded string
Example: `MNTxMmQxNjgyYjFhNjI3Y2Q2ZmY2OGIzZjIxNmU3N2I6`
`MTVkNDVkMTgyYWRiMTc5MmUwMGQ0NThlNjAxYjA0NjE=` | 64-character string
Example: `6b128e17fdf9b00e2cdb101ccf9fbbe1`
`3e318f770ee1b73c97b5f96778e9a21f` |
| Each application has one basic token | Multiple bearer tokens can exist for different users within an application |
| Copy from the [API dashboard](https://app.signnow.com/webapp/api-dashboard) | Request from [`POST /oauth2/token`](/docs/oauth2/operations/post__oauth2_token) |
| Use to get authorized when generating a bearer token | Use to get authorized for most* other requests |
| Use in the Authorization header after the word “Basic”:
` Basic {{basic_authorization_token}} ` | Use in the Authorization header after the word “Bearer”:
`Bearer {{access_token}}` |
\*Several requests work with basic authorization:
- [Create user](/docs/user/operations/post-user)
- [Reset password](/docs/user/operations/user-forgot-password)
- [Activate/deactivate signing link](/docs/signing-link/operations/put-v2-application-signing-links-signing_link_short_url_id)
- [Get signing links](/docs/signing-link/operations/get-v2-application-signing-links)
- [Get event subscriptions](/docs/basic-auth/operations/get-event-subscriptions)
- [Delete event subscriptions (basic auth)](/docs/basic-auth/operations/delete-event-subscription)
- [Edit event subscriptions (basic auth)](/docs/basic-auth/operations/update-event-subscription)
For quick authorization and testing, use API keys generated in the API dashboard.
## SignNow login options
Before diving into the authentication process, let’s review how end-users can log in to SignNow.
SignNow supports the following login methods:
- Using account email and password
- Using third-party applications:
- Facebook login
- Microsoft login
- Google login
- SSO (Single Sign-on) via SAML
Let’s briefly discuss the last two methods.
### Facebook login
Facebook login is an OAuth-based authentication method that allows users to log in to SignNow using their Facebook account.
**Benefits**:
- Users don’t need to remember additional passwords.
- Seamless experience for users already logged into Facebook.
- Grants access to basic user data (e.g., name, email) for account creation.
**Usage example:**
A user clicks **Facebook** on the SignNow login page, enters the email and password from the Facebook account, and authorizes the app.
### Microsoft login
Microsoft login uses Microsoft’s OAuth-based authentication to enable users to log in to SignNow using their Microsoft credentials (e.g., Office 365, Outlook, Teams accounts).
**Benefits:**
- Commonly used in enterprise environments for integration with Azure Active Directory (AAD).
- Supports single sign-on (SSO) across Microsoft services and partner apps.
- Offers robust security features like multi-factor authentication (MFA).
**Usage example**:
A user clicks **Microsoft** on the SignNow login page, selects their account, and gets access to their SignNow organization.
### Google login
Google login uses OAuth 2.0 and OpenID Connect protocols to let users sign in to SignNow with their Google account.
**Benefits:**
- Widely used and trusted by millions of users worldwide.
- Allows developers to request access to basic user info (e.g., email, name) or extended permissions (e.g., Google Drive files).
- Strong security with features like two-factor authentication (2FA).
**Usage example:**
A user clicks **Google** on the SignNow login page, selects their account, and gains instant access to SignNow without needing to create a separate password.
### SSO via SAML (Security Assertion Markup Language)
SAML is an open standard used for single sign-on (SSO) in enterprise environments. It allows authentication data to be exchanged securely between an identity provider (IdP) (ADFS, Auth0, Azure AD, Okta, OneLogin, and Salesforce Identity) and a service provider (SP) (SignNow).
**Benefits:**
- Eliminates the need for multiple passwords by enabling SSO across many apps.
- Often used in corporate or organizational environments.
- Secure communication between IdP and SP using XML-based assertions.
**Usage example:**
With SSO enabled, SignNow users who are already authenticated through their identity provider can automatically log into SignNow without the need to manage a separate username and password.
## Generate an API key
The easiest way to authenticate your application is by using an API key, which is generated automatically when you create an application.
- Go to the [API dashboard](https://app.signnow.com/webapp/api-dashboard) > **Apps and Keys** and select the application.
- On the **API Keys** tab, copy the API key.
- Add the API key into the `Authorization` header of your API request.
**Example API request with the API key in the Authorization header (Send a freeform invite)**
```bash
curl --request POST \
--url https://api.signnow.com/document/{{document_id}}/invite \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{API_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"document_id": "a485bc7c95274c3cb6614c4a1fc469510d6aWWWW",
"to": "signer@email.com",
"from": "sender@email.com",
"redirect_uri": "https://redirect-uri.com",
"close_redirect_uri": "https://close-redirect-uri.com",
"redirect_target": "blank",
"cc": [
"cc-recipient@email.com"
],
"subject": "You have been invited to sign a document",
"message": "You have been invited to sign a document",
"cc_subject": "Subject for CC",
"cc_message": "Message for CC",
"sms_message": "{sender_email} your document is here {invite_url}",
"language": "en"
}'
```
## Generate access token (bearer token)
We will walk through the process of generating an access token:
- using SignNow account credentials
- for users who signed up with third-party applications
- with a refresh token
- without credentials (using the authorization code)
## Step 1. Get basic authorization token
1. Go to the [API dashboard](https://app.signnow.com/webapp/api-dashboard).
2. On the **Apps and Keys** tab, select the application.
3. Select the **OAuth 2.0** tab and copy the **Basic Authorization Token**.
## Step 2. Generate access token (bearer token)
Use the [`POST /oauth2/token`](/docs/oauth2/operations/post__oauth2_token) request to generate a bearer token. You can generate an access token using on of the following authorization grants:
### Password grant
Use the application **Basic Authorization Token** and your account credentials. This method works only for application owners: for any other user, the token request fails with an access denied error (code `11005001`) even if the same credentials work for logging in to the SignNow web application. To authenticate users who don't own the application, use the [Authorization code grant](/docs/authentication#authorization-code-grant).
> If you log in to your SignNow account using third-party applications (Google, Facebook, or Microsoft), you need to reset a password and create a new one.
Learn how to reset a password
- Log out of your SignNow account.
- Click **Forgot password?** on the login page.
- Enter the email address associated with your third-party application and click **Recover password**.
- Check your email inbox and click the link. Enter your new password and click **Change password**.
- You will be redirected to the login page. Enter your email address and a new password to ensure everything works as expected.
Now you can use the new password for [`POST /oauth2/token`](/docs/oauth2/operations/post__oauth2_token) request.
```bash
curl --request POST \
--url https://api.signnow.com/oauth2/token \
--header 'Authorization: Basic {{basic_authorization_token}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username={{account_email}}' \
--data-urlencode 'password={{account_password}}' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=*'
```
```json
{
"expires_in": "1584793649",
"token_type": "bearer",
"access_token": "XXXX55867b471d39c73f3baedfad51e7fef9a7116bd07224d048e6366651YYYY",
"refresh_token": "XXXX8c3ce4fda49db8ff1d45533117857e7f8d3182c5c7cd8ef20cc95b36YYYY",
"scope": "*",
"last_login": 1
}
```
> For all the grant types, you can use the `scope` parameter to manage the permissions for the issued token. The default `*` value grants all permissions and allows the token to perform any API action.
Using `scope`, you can define a custom list of accessible URLs.
For example: `document/* GET/user` will allow access to:
- all routes starting with `/document/` - `GET /user` route
### Refresh token grant
Use this method if the access token expires. Find a refresh token in the response to the previous authorization request.
```bash
curl --request POST \
--url https://api.signnow.com/oauth2/token \
--header 'Authorization: Basic {{basic_authorization_token}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={{refresh_token}}' \
--data-urlencode 'scope=*'
```
```json
{
"expires_in": "1584793649",
"token_type": "bearer",
"access_token": "XXXX55867b471d39c73f3baedfad51e7fef9a7116bd07224d048e6366651YYYY",
"refresh_token": "XXXX8c3ce4fda49db8ff1d45533117857e7f8d3182c5c7cd8ef20cc95b36YYYY",
"scope": "*",
"last_login": 1
}
```
### Authorization code grant
Use an authorization code to generate an access token for users who are not application owners.
**1\) Retrieve the required query parameters**
To generate an authorization code, you need the following query parameters:
- `client_id`: can be found on the API dashboard. Go to **Apps and Keys** > select your application > select the **OAuth 2.0** tab > copy the **Client ID**.
- `redirect_uri`: any URL that is opened to generate a code. Usually, it's a customer's URL with a logic that reads and uses the authorization code in the integration.
- `response_type`: always set to `code`.
**2\) Generate the authorization URL**
Use the query parameters to create an authorization URL, and share it with your users.
**The URL example:**
```json
https://app.signnow.com/authorize?client_id={{client_id}}&response_type=code&redirect_uri=https://www.signnow.com
```
**3\) [Get the authorization code](/docs/oauth2/operations/get-oauth2-userauth)**
When the user opens the link, they’ll be prompted to log in with their SignNow credentials and grant your app access to their SignNow account.
After the successful login, the user will be redirected to the `redirect_uri`, which includes the authorization code as a query parameter.
**Example of the redirect URL with the authorization code:**
```json
https://www.signnow.com/?code=xxxxxxc3110eb7e741888449e0873b0d43e43f81ccfdf2131c8f90b02yyyyyyy
```
**4\) Generate an access token (bearer token)**
To exchange the authorization code for a bearer token, you’ll need:
- The application’s [Basic Authorization Token](/docs/authentication#step-1-get-basic-token)
- The authorization `code` from the redirect URL
> The `basic_authorization_token` must belong to the same application as the `client_id` used in the authorization URL.
Send the request.
```bash
curl --request POST \
--url https://api.signnow.com/oauth2/token \
--header 'Authorization: Basic {{basic_authorization_token}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code={{authorization_code}}' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'scope=*'
```
```json
{
"expires_in": 2592000,
"token_type": "bearer",
"access_token": "XXXX55867b471d39c73f3baedfad51e7fef9a7116bd07224d048e6366651YYYY",
"refresh_token": "XXXX8c3ce4fda49db8ff1d45533117857e7f8d3182c5c7cd8ef20cc95b36YYYY",
"scope": "*",
"last_login": 1
}
```
The successful request returns the access token (bearer token) and a refresh token.
### API key vs. access token (bearer token): key differences
| Feature | API Key | Access Token |
|-------------------------|-------------------------------------------------|-----------------------------------------------------------|
| **How to create** | In the API dashboard | Send [`POST /oauth2/token`](/docs/oauth2/operations/post__oauth2_token) request |
| **Purpose** | Identifies the application or user making API requests | Proves authentication and authorization for a specific user or session |
| **Security level and expiration** | Less secure and doesn't expire | More secure, expires after a set time and requires refreshing |
| **Authentication** | Simple; included in Authorization headers. Example: `Bearer {{API_key}}` | Part of OAuth 2.0 authentication flow. Included in Authorization headers. Example: `Bearer {{access_token}}` |
| **Scope and permission** | All SignNow API requests | All SignNow API requests |
### Which authentication method fits your integration
| Integration type | Recommended method |
|---|---|
| Server-to-server automation that acts as a single SignNow account, for example a backend that sends all documents from one integration account | An API key from that account's [API Dashboard](/docs/account#api-keys), or the password grant with the account credentials and a refresh token. API keys don't expire, so there is no token refresh logic to maintain. |
| An application that acts on behalf of individual SignNow users | The authorization code grant: users authorize your application without sharing their credentials. |
| Short-lived scripts and testing | The password grant. |
> **Note**: Supported OAuth2 grant types: `password`, `refresh_token`, and `authorization_code`.
Keep API keys, the basic authorization token, and user credentials in a secure secrets manager, and never expose them in client-side code. For details, see the [Go-live checklist](/docs/go-live-checklist). To revoke an API key immediately, delete it in the API Dashboard: the application using that key stops working.
## Common 401 errors and solutions
The table below lists the most common causes of a `401 Unauthorized` error when sending API requests, and how to fix them.
| Cause | Description | How to fix |
|---|---|---|
| **The access token is incorrect** | The `Bearer` token passed in the `Authorization` header is incorrect. | Make sure you are copying the access token correctly from the [`POST /oauth2/token`](/docs/oauth2/operations/post__oauth2_token) response. |
| **The access token has expired** | The access token has reached its expiration time and is no longer valid. | Request a new access token via [`POST /oauth2/token`](/docs/oauth2/operations/post__oauth2_token) or use the refresh token to obtain a new one. |
| **The access token has been revoked** | The access token was manually revoked by the user or admin. | Re-authenticate via [`POST /oauth2/token`](/docs/oauth2/operations/post__oauth2_token) to obtain a new access token. |
| **The API key is incorrect** | The API key passed in the `Authorization` header is incorrect. | Copy the correct API key from your SignNow API dashboard. |
| **The API key has been revoked** | The API key was deleted or revoked in the SignNow API dashboard. | Generate a new API key in your SignNow API dashboard. |
| **The `Authorization` header is missing** | The request does not include the `Authorization` header. | Add `Authorization: Bearer {{access_token}}` or `Authorization: Bearer {{api_key}}` to the request. |
| **The `Authorization` header format is incorrect** | The `Authorization` header value is not formatted correctly. | Use the correct format: `Bearer {{access_token}}` or `Bearer {{api_key}}`. |
| **The account has been suspended** | The SignNow account has been suspended or deactivated. | Contact SignNow support for assistance. |
---
## iFrame authorization for integrated users
When building SignNow integration in your system, you can streamline user login using an embedded iFrame:
1\) The user clicks a button in your system to trigger a SignNow action.
2\) The SignNow login screen opens in an embedded iFrame. The screen offers all the SignNow login options, including SSO.
**Example: user logs in to SignNow within Salesforce**
**Step 1**
**Step 2**
3\) The user logs in to SignNow without leaving your system.
4\) The user is requested to allow the integration app to access their SignNow account.
5\) Once authorized, the user can use the SignNow functionality directly from your system.
> This authorization flow doesn't need to occur every time the user needs to use the integration. You can implement logic to store the user’s session and reuse the bearer token.
## Try out in Postman
[Access](https://www.postman.com/signnow-api/signnow-public-collection/collection/tmopsan/signnow-code-grant-generation-collection?action=share\&creator=29919567) the authorization flow in Postman to choose from various authentication methods for your integrations.
---
*Full page: https://docs.signnow.com/docs/authentication*