Authentication

The Borderbolt API uses OAuth2 Client Credentials flow for authentication. This flow is designed for server-to-server communication where you authenticate using a client ID and client secret.

Obtaining API Credentials

Log in to your Borderbolt account
Navigate to Settings → API Documentation
Click Generate API Credentials
Store your client_id and client_secret securely

Important: The client secret is only shown once. Store it securely - you cannot retrieve it later.

Requesting an Access Token

Use the OAuth2 Client Credentials flow to obtain an access token:


curl -X POST https://app.borderbolt.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "scope": "declarations:read declarations:write"
  }'

Request Parameters

Parameter	Required	Description
`grant_type`	Yes	Must be `client_credentials`
`client_id`	Yes	Your OAuth2 client ID
`client_secret`	Yes	Your OAuth2 client secret
`scope`	No	Space-separated list of scopes (defaults to all granted scopes)

Response


{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "scope": "declarations:read declarations:write"
}

Field	Description
`token_type`	Always `Bearer`
`expires_in`	Token lifetime in seconds (3600 = 1 hour)
`access_token`	JWT token to use for API requests
`scope`	Granted scopes for this token

Using Access Tokens

Include the access token in the Authorization header for all API requests:


curl -X GET https://app.borderbolt.com/api/v1/declarations \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -H "Accept: application/json"

Token Management

Get Token Information

Retrieve information about the current access token:


curl -X GET https://app.borderbolt.com/oauth/tokeninfo \
  -H "Authorization: Bearer your-access-token"

Response:


{
  "client_id": "your-client-id",
  "scopes": ["declarations:read", "declarations:write"],
  "expires_at": "2026-03-25T15:30:00.000000Z"
}

Revoke Token

Revoke an access token before it expires:


curl -X POST https://app.borderbolt.com/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-access-token"
  }'

Available Scopes

Scopes control access to specific API resources. Request only the scopes you need.

Declarations

Scope	Description
`declarations:read`	View declarations and lines
`declarations:write`	Create and update declarations
`declarations:delete`	Delete draft declarations
`declarations:submit`	Submit declarations to customs

Transit (NCTS5)

Scope	Description
`transit:read`	View transit declarations
`transit:write`	Create and update transit declarations
`transit:delete`	Delete draft transit declarations

Customers

Scope	Description
`customers:read`	View customer master data
`customers:write`	Create and update customers
`customers:delete`	Delete customers

Reports

Scope	Description
`reports:read`	View and run reports
`reports:export`	Export reports to CSV

Item Master

Scope	Description
`item_master:read`	View item master data
`item_master:write`	Create and update items
`item_master:delete`	Delete items

Guarantees

Scope	Description
`guarantees:read`	View guarantee balances and DVA overview

Dossiers

Scope	Description
`dossiers:read`	View dossiers
`dossiers:write`	Create and update dossiers
`dossiers:delete`	Delete dossiers

Invoices

Scope	Description
`invoices:read`	View invoices
`invoices:write`	Create, update, and finalize invoices
`invoices:delete`	Delete draft invoices

Best Practices

Token Caching: Access tokens are valid for 1 hour. Cache tokens and reuse them until they expire to minimize token requests.

Secure Storage: Never commit client secrets to version control. Use environment variables or secure credential storage.

Scope Minimization: Request only the scopes your application needs. This follows the principle of least privilege.

Error Responses

Invalid Credentials


{
  "error": "invalid_client",
  "error_description": "Client authentication failed",
  "message": "Client authentication failed"
}

HTTP Status: 401 Unauthorized

Invalid Scope


{
  "error": "invalid_scope",
  "error_description": "The requested scope is invalid, unknown, or malformed",
  "message": "The requested scope is invalid, unknown, or malformed"
}

HTTP Status: 400 Bad Request

Rate Limiting

API requests are rate-limited per client. See the Error Reference for details on rate limit headers and handling 429 responses.