API credentials

An API credential lets one of your organization’s systems, such as an ERP or a billing system, create and send envelopes without manual work. Each credential acts only within your organization and with the role you assign. It consists of a Client ID and a Client secret, with which the system obtains its access tokens.

Who: organization admins and platform admins. Where: Settings, API credentials tab.

Create a credential

1. Press New credential.

2. Enter the Label, which says which system will use it; for example, “Billing system”.

3. Under Access, choose the Workspace and the Role (Viewer, Auditor or Manager). The default is Manager in General.

4. Press New credential. The Save this secret now dialog shows the Client ID and the Client secret. Copy them into your organization’s secret manager before closing it.

The secret is shown once

bb-sign keeps no recoverable copy of the secret. If you lose it, rotate the credential to get a new one.

What a credential can do

A credential acts with the role you assigned in each workspace, like a person. As Manager in General, it creates, sends and cancels envelopes and downloads documents of that workspace; as Viewer, it reads the envelopes. To give it access to other workspaces, add it as a member from Workspaces and members. Each credential’s row shows the workspaces it acts in.

Administrative tasks, such as creating credentials, configuring webhooks or managing workspaces and members, always remain with the people who administer the organization. The reason is in the Permissions matrix.

Your organization can hold up to 10 active credentials.

Rotate the secret

Rotate generates a new secret for the same Client ID. The previous secret stops working immediately, so coordinate the rotation with the team that deploys the integration. Confirm with Rotate secret and save the new secret the dialog shows.

Revoke a credential

Revoke disables the credential permanently. New requests are refused immediately, and the tokens the credential had already obtained stop working when they expire, within 300 s. The row shows the exact time.

The revoked credential stays in the list for 90 days so you can review it. Creation and revocation are recorded in the audit trail.

Status	Meaning
Active	Obtains tokens and acts in its workspaces.
Revoked — draining	Obtains no more tokens; current ones work until the time shown.
Revoked	No access. Leaves the list when the period ends.

Error messages

Message	What happened and what to do
““label” was created but could not be given its access, so it was revoked. Nothing can use it.”	The workspace access could not be set up and the credential was revoked for safety. Create it again in a moment.
“Could not create the credential.”	The maximum number of active credentials was reached or a temporary problem occurred. Revoke one you do not use or try again later.

Developer quickstartHow to obtain a token with the ID and the secret, and make the first API call.

Machine authenticationWhat the token contains, how long it lasts and what each error means.