Skip to content
Binary BridgesBinary BridgesBinary Bridges Docs
Developers

Quickstart

This guide takes your integration from a new credential to a 201 from POST /api/v1/envelopes: an envelope created in your organization.

Requirements: a bb-sign account with the org admin role (or help from someone who has it), and Java 17 or newer, or Node 20 or newer.

1. Get a credential

Section titled “1. Get a credential”

An API credential lets a system call bb-sign on your organization’s behalf, with access limited to that organization.

  1. Sign in to bb-sign and open Settings, tab API credentials.
  2. Select New credential. Give it a label that identifies the system that will use it, for example “Billing system”.
  3. Under Access, keep the default workspace and role unless you need others: “General with Manager is the default.”
  4. Copy the Client ID and the Client secret.

Settings appears in the sidebar for org admins. If you do not have that role, ask your organization’s bb-sign admin to create the credential and send you the two values.

You also need two URLs. In production they are:

Value
API base URL https://sign-api.binarybridges.co
Token URL https://auth.binarybridges.co/realms/bbsign/protocol/openid-connect/token

Set them as environment variables, outside your source code:

Ventana de terminal
export BBSIGN_BASE_URL="https://sign-api.binarybridges.co"
export BBSIGN_TOKEN_URL="https://auth.binarybridges.co/realms/bbsign/protocol/openid-connect/token"
export BBSIGN_CLIENT_ID="..."
export BBSIGN_CLIENT_SECRET="..."

2. Verify the credential

Section titled “2. Verify the credential”

Before writing code, confirm the credential obtains a token:

Ventana de terminal
curl -s -X POST "$BBSIGN_TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$BBSIGN_CLIENT_ID" \
  -d client_secret="$BBSIGN_CLIENT_SECRET"

The response is JSON with access_token. If you receive invalid_client, the id or secret is wrong: copy them again, or rotate the secret and try again.

With the credential verified, any later failure is easier to diagnose.

3. Install an SDK

Section titled “3. Install an SDK”

The API is standard HTTP and the reference documents it in full, so the SDK is optional. The SDKs handle token refresh, retries and webhook signature verification.

No installation required. The examples use curl and jq.

4. Create an envelope

Section titled “4. Create an envelope”
Ventana de terminal
TOKEN=$(curl -s -X POST "$BBSIGN_TOKEN_URL" \
  -d grant_type=client_credentials \
  -d client_id="$BBSIGN_CLIENT_ID" \
  -d client_secret="$BBSIGN_CLIENT_SECRET" | jq -r .access_token)


curl -s -X POST "$BBSIGN_BASE_URL/api/v1/envelopes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My first envelope",
    "otpRequired": false,
    "expiresAt": "2026-12-01T00:00:00Z",
    "signers": [{"email": "someone@example.com", "name": "Someone", "signOrder": 1}]
  }'

The 201 response confirms the envelope exists, in DRAFT status.

Choose a workspace

Section titled “Choose a workspace”

Every envelope belongs to a workspace, and a credential accesses the workspaces assigned to it. A new credential is Manager in your organization’s General workspace unless the admin chose another. Without workspaceId, the envelope is filed in General. To file it in another workspace, list the workspaces available to the credential and send one’s id:

Ventana de terminal
curl -s "$BBSIGN_BASE_URL/api/v1/workspaces" -H "Authorization: Bearer $TOKEN"
# [{"id":"6f1c...","name":"General","isGeneral":true}, {"id":"a2d9...","name":"HR","isGeneral":false}]


curl -s -X POST "$BBSIGN_BASE_URL/api/v1/envelopes" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title": "Offer letter", "workspaceId": "a2d9...", "signers": [{"email": "someone@example.com", "name": "Someone"}]}'

A workspace the credential cannot create in returns 404 WORKSPACE_NOT_FOUND, the same as one that does not exist. Envelopes in workspaces without access return 404 NOT_FOUND and do not appear in lists.

5. Send the envelope for signature

Section titled “5. Send the envelope for signature”

An envelope in DRAFT has not been sent yet. For the signers to receive it:

  1. Attach a document: POST /api/v1/envelopes/{id}/documents (multipart), or upload it first with POST /api/v1/documents and send the ids as documentIds when you create the envelope.
  2. Send it: POST /api/v1/envelopes/{id}/send. bb-sign emails each signer a link and returns their signing tokens. From this point on, the documents and signers are fixed.
  3. Receive status changes: set up a webhook instead of polling.

From credential to signed document shows each of these calls in the three languages.

Troubleshooting

Section titled “Troubleshooting”
Symptom Meaning Action
invalid_client from the token URL The client id or secret is wrong Copy them again or rotate the secret
401 from the API The token was rejected or has expired (a token is valid for 300 s) If you built the request manually, check the Bearer prefix; request a new token
403 The credential is valid, but the operation is not available to credentials Confirm the operation is listed in the API reference; administration is done in the UI
404 WORKSPACE_NOT_FOUND The credential has no role that allows creating in that workspace, or the workspace does not exist Omit workspaceId, or ask the admin to grant the credential a role in that workspace from Settings, tab Workspaces
400 with no detail Usually a malformed body Compare it field by field with the example; expiresAt must be ISO-8601
NoClassDefFoundError at runtime (Java) -DpomFile was omitted during install Reinstall with that parameter
ERR_REQUIRE_ESM (JavaScript) The package is ESM only Use import

If your case is not in the table, write to us with a description of what you were doing.

Reference

Section titled “Reference”

© 2026 Binary Bridges S.A.S. All rights reserved.