API Authentication

DocSpring uses API tokens for authentication. You can authenticate using HTTP basic authentication. Use your API token ID as the username, and the API token secret as the password.

Manage API TokensManage your API tokens in the DocSpring dashboard

Environment Variables

All DocSpring API clients, and the DocSpring CLI, read your credentials from environment variables. Set the following environment variables, and the client will automatically use them:

• DOCSPRING_TOKEN_ID - Your API token ID
• DOCSPRING_TOKEN_SECRET - Your API token secret

This allows you to keep your credentials out of your code:

export DOCSPRING_TOKEN_ID="your_token_id"
export DOCSPRING_TOKEN_SECRET="your_token_secret"

The clients send requests to our US region by default. They also read the region or host:

export DOCSPRING_REGION="EU" # US or EU (defaults to US)
export DOCSPRING_HOST="docspring.yourcompany.com" # For on-premise deployments

Credentials and a host that you pass to the client take precedence over these variables, and an empty value counts as not set. A host, passed in or from DOCSPRING_HOST, takes precedence over a region, even one you pass to the client. Without credentials, requests fail with a 401 unauthorized error.

Then initialize the client without passing credentials:

Ruby

client = DocSpring::Client.new

Python

from docspring import Client
client = Client()

JavaScript

const DocSpring = require("docspring");
const client = new DocSpring.Client();

TypeScript

import * as DocSpring from "docspring-ts";
const client = new DocSpring.Client();

PHP

$config = DocSpring\Configuration::getDefaultConfiguration();
$api = new DocSpring\Api\Client(null, $config);

Java

com.docspring.Client api = new com.docspring.Client();

C#

var api = DocSpring.Client.Client.EnvClientFactory.NewClient();

Go

apiClient := client.NewClient("", "")

Elixir

conn = Docspring.Connection.new()

Rust

let client = docspring::Client::from_env()?;

HTTP Basic Authentication

“HTTP basic authentication” means that you need to send an Authorization header with the value Basic followed by token_id:token_secret in Base64 encoding.

Some tools such as curl can create the Authorization header for you:

curl -u API_TOKEN_ID:API_TOKEN_SECRET \
  https://sync.api.docspring.com/api/v2/authentication

Or you can create the Base64 encoded string manually:

# echo -n "API_TOKEN_ID:API_TOKEN_SECRET" | base64
QVBJX1RPS0VOX0lEOkFQSV9UT0tFTl9TRUNSRVQ=

curl -H "Authorization: Basic QVBJX1RPS0VOX0lEOkFQSV9UT0tFTl9TRUNSRVQ=" \
  https://sync.api.docspring.com/api/v2/authentication

API tokens and team members

Each API token belongs to a team member, and API requests made with it act as that team member. The API tokens page shows who each token belongs to and when it was last used.

When you remove a team member who has active API tokens, you choose whether to transfer their tokens to another team member or revoke them. A transferred token keeps the same secret, so integrations that use it keep working. If the person you removed may still have a copy of the secret, create a new token for the integration and revoke the old one once the integration has switched over.

A token whose team member is no longer in the account is refused. The account owner can transfer it to a team member from the API tokens page.

---

Next Steps

API Reference: Test AuthenticationView code samples to learn how to set up authentication for your API client.
Click the Test Request button to try it out using your own API token.